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This publication complements the Systems Reference 
Library publication IBM .S^stem/360, PL/I Subset 
E§I§5§S£§-.M§DS§i» Order No. GC28-8202. Its purpose is 
to aid the proorrammer and to familiarize him with the 
techniques of PL/I programming. This publication 
therefore provides all information that is not part of 
the PL/I Subset Reference Manual but required by the 
programmer to write programs in the PL/I Subset lan- 
guage and to have them compiled and executed in the 
DOS/TOS environment. 

The main topics covered in this publication are: 

• The DOS/TOS environment 

• PL/I data file organization 

• Storage requirements of PL/I programs and program 
elements 

• The overlay facility 

• Listings produced for PL/I programs 

• Restrictions to the PL/I Subset language 

In some instances, the programmer may desire 
detailed additional information on topics not directly 
connected with PL/I. A list of all pertinent Systems 
Reference Library publications is provided in the 
Int ro duction section of this publication. 
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SUMMARY OF CHANGES 

The DOS system now provides for the 
support of private core-image libraries. 
|n a DOS system supporting the batched- 
ob foreground and private core-image 
libraries, the compiler and the linkage 
^ditor may execute in a foreground or in 
'the background partition. 

A description of errors that may arise 
due to multiple secondary entry points 
or due to multiple CSECT names has been 
added . 



When processing INDEXED files, the KEY 
condition may arise in a number of cases. 
It is described how the programmer may 
identify specific situations at execution 
time. 

A brief description of hardware stops 
caused by severe programming errors has 
been included. 

Also added was an appendix containing 
programming examples together with ex- 
planations . 



Seventh_Eaition (April, 1971) 

This is a major revision of GC2U -9005-5. 

Changes to the text and to the illustrations as well as additions are 
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Introduction 



This publication complements the Systems 
Reference Library publication IBM System/ 
360, PL/I Subs et Reference Ma nual , Order 
No. GC28-8202 (hereafter referred to as the 
Subset Reference Manual) , It provides all 
information that is not part of the lan- 
guage specifications but required by the 
programmer to write programs in the PL/I 
Subset language and to have them compiled 
and executed in the DOS/TOS environment. 



A list of all SRL publications the pro- 
grammer may have to refer to is given 
below: 

IBM System/360 Disk Operating System, 
System Programmer's Guide, 
Order No. GC2£|-5073 

IBM Sy3tem/360 Operating System, PL/I 
Library Computational Subroutines, 
Order No. GC28-6590 



This publication is divided into four 
logical parts: 

Part I - provides all information regard- 
ing the DOS/TOS environment, PL/ 
I data file organization includ- 
ing the ENVIRONMENT attribute, 
linkage between PL/I and 
Assembler modules, and PL/I pro- 
gramming in the DOS/TOS 
environment. 

Part II - provides all information regard- 
ing storage requirements of pro- 
grams written in the PL/I Subset 
language, and a description of 
the overlay facility. 

Part III - describes all listings and diag- 
nostic messages produced for PL/ 
I programs running under DOS/TOS 
control. 

Part 17 - Appendix, Some of the individu- 
al appendixes provide informa- 
tion taken out of the corres- 
ponding sections to improve the 
readability, e.g., a list of all 
available I/O subroutines. The 
remaining appendixes furnish 
additional reference information 
the PL/I programmer might find 
useful . 

The last section of the Appendix lists 
the implementation-dependent restrictions 
to the PL/I Subset language as it is 
described in the Subset Reference Manual. 
The individual restrictions are listed in 
alphabetical order. 

To free the programmer of the necessity 
of referring to other publications for 
additional information, this publication is 
made as self-supporting as possible by dup- 
licating some of the information given 
elsewhere. However, should this publica- 
tion not give all the details the programm- 
er needs for solving his problem, these 
details can be found in the pertinent SRL 
publication. 



IBM System/360 Principles of Operation, 
order No, GA22-6821 

IBM System/360 Disk and Tape Operating Sys- 
tems, Concepts and Facilities, 
Order No. GC24-5030 

IBM System/360 Disk and Tape Operating Sys- 
tems, Utility Program Specifications, 
Order No, GC2U-3U65 

IBM System/360 Disk Operating System, Sys- 
tem Control and System Service Programs, 
Order No, GC24-5036 

IBM System/ 360 Tape Operating System,, Sys- 
tem Control and System Service Programs, 
Order No. GC2U-3431 

IBM System/ 360 Disk Operating System, 
Supervisor and Input/Output Macros, 
Order No. GC24-5037 

IBM System/360 Tape Operating System, 
supervisor and Input/Output Macros, 
Order No. GC2U-3432 

IBM System/360 Disk Operating System, Data 
Management Concepts, Order No. GC24-3427 

IBM System/360 Tape Operating System, Data 
Management Concepts, Order No, GC24-3a30 

IBM System/360 Disk Operating System, PL/I 
DASD Macros, Order No. GC24-5059 



Minimum Requirements for Compilation 

1. 16,384 (16K) bytes of core storage on 
one of the compatible models of System/ 
360 (not Model 20, 44). The compiler 
itself requires lOK, More than lOK are 
required if SYSIPT, SYSLST, and/or SYS- 
PCH are DASD files. This is a system 
generation option, 

2. a. Either one IBM 2311 Disk Storage 

Drive or one IBM 2314 or 2319 
Direct Access Storage Facility or 
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b. four IBM Magnetic Tape Drives of 
the series 2400, 2420, or 3420. A 
7 -track tape may be used for SYSRE- 
S. The use of a 9-track tape for 
SYSRES will improve the perfor- 
mance. The data conversion feature 
is required for 7-track drives. 
One additional tape drive is 



operation, 



Additional machine features required for 
arithmetic, compare, and conversion are 
listed in Figure 1. 



Note: At EXEC time all IJKSnn transients 
must be available in the core-image 
library. 



3. One card read/punch or one card reader 
and one card punch, 

4. One printer. 

5. One IBM 1052 Printer-Keyboard (required 
for operator-to-system communication) . 

6. The optional supervisor feature Program 
Interrupt (PC) . 

Note: Either one or both of the units 
listed under items 3 and 4 may be replaced 
by one additional magnetic tape drive per 
replaced unit. 

The speed of compilation is greatly 
reduced if (1) the source program contains 
more than 80 programmer-defined identi- 
fiers, and (2) a 16K system is used to com- 
pile a program greater than 16K, 

For determination of the required work- 
file space refer to Workfile Requirements 
in Appendix G of IBM Syste m/ 360 Disk 
Operating System, _S^stero Generation and 
Maintenance, Order No, GC24-5033. 



Minimum Requirements for Execution 

The execution-time requirements depend on 
the requirements of the system and the 
object program. 



Maximum Configuration Supported 

The following units and features are 
supported: 



1. All of the units and features specified 



# r% J — 1- 
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All of the following devices: 

IBM 2540* 

IBM 1403 

IBM 3211 

IBM 1404 (for continuous forms only) 

IBM 1442N1 

IBM 1442N2 

IBM 1443 

IBM 2501 

IBM 2520B1 

IBM 2520B2 

IBM 2520B3 

IBM 1445 

IBM 2321 



♦The Punch/Read Feed (PRF) special fea- 
ture is not implemented by PL/I- 



Additional ma' 
ion bytes. 
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r T T 

Comparison of /With | Coded 
Arithmetic With/And | Fixed 
Convert To j Decimal 



T T T 

I 1 Numeric 
Fixed I Coded [Fixed, [Numeric 
Binary | Float j Sterling I Float 






From 



—\ 



Coded fixed decimal | D 






Fixed binary 



I D,F= 



Coded float 



I D,F 



D,F2 j D,F 



D,F2 






I D,F 
-+ 



D,F 



D,F 



D,F 



Bit I Char. 



NP 



NP 



NP 



Numeric fixed and 
sterling 



D,F2 ] D,F I 



D,F 



X^ 



Numeric float | D,F 

Bit I D 

Character | NP 
J. 



D,F I D,F I D,F 

X I F I D 

NP 1 NP I NPi 
X X 



D,F 
D,F 
Npa- 



i + 



+ — 4- 



D,,F I X^ 
X t X 

X 1 X 

X 



D - Decimal feature required. 

F - Floating-point feature required. Conversion only. 

NP - Not permitted. 

X - No special features required. 



^ - Conversion only. 

2 - Floating-point feature only if scale factor not equal to zero. 

L . : 

Figure 1. Additional Machine Feature for Arithmetic, Comparison, or Conversion 
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Running Programs Under DOS/TOS Control 



This section describes the compilation and 
execution of PL/I programs under control of 
the Disk and Ta''^e O'^eratincj S'"steiTis • The 
pertinent terminology, control statements, 
and their formats are discussed when 
required. 



Basic Terminology 

It is convenient to refer to each stage of 
program development by a particular name, 
because just the term program would be too 



execution. External procedures that are 
never active simultaneously may use the 

part of the program that is in storage only 
for a fraction of the execution time is 
referred to as an overlay, using the MAIN 
procedure as an overlay is not permitted. 
Each overlay as well as that part of the 
program that resides in storage throughout 
the execution of the object program is 
referred to as a phase. A phase consists 
of one or more external procedures. For 
detailed information refer to the sections 



In program development, the programmer 
writes sets of source statements that may 
form a complete program or part thereof. A 
card deck containing one external procedure 
written in the PL/I Subset language is 
referred to as a source module. A source 
module is the unit that is processed during 
a compilation. The compilation results in 
one or two object modules. The first 
object module is produced by the PL/I com- 
piler for all of the file declarations, if 
any, contained in the source module. The 
second object module is produced for the 
source module. Object modules can be 
loaded by the DOS/TOS Linkage Editor pro- 
gram and then executed. An object module 
consists of standard E3D (External Symbol 
Dictionary), TXT (Text), RLD (Relocation 
Dictionary) cards, and one END card. 



To start the execution of a PL/I pro- 
gram, control must be transferred from the 
Disk or Tape Operating System to the object 
program. The external procedure to which 
control is transferred from the Job Control 
program must have the option MAIN. 

Some parts of the object program may not 
be required in storage throughout its 



Some standard procedures such as PL/ I 
built-in functions or conversion subrou- 
tines have been incorporated into the relo- 
catable library as library sub routines . 
Only the code required for calling these 
subroutines is compiled into the object 
module. The library subrGUtines themselves 
are incorporated into the appropriate 
phases by the autolink feature of the DOS/ 
TOS Linkage Editor program. 



Extra code is required to allow some 
housekeeping during the execution of a PL/I 
program. This code, which is referred to 
as overhead, may either be generated in- 
line in an object module or incorporated 
due to an explicit library subroutine call. 



The relationship between the user's PL/I 
mainline program, the PL/I control program, 
and the DOS/TOS system is shown in Figure 
2. 



Note: The PL/I control program is a set of 
library routines in the relocatable library 
which are included into object programs at 
linkage-edit time and perform certain con- 
trol functions at execution time. 
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Miscellaneous Subroutines 
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J I/O Transmitters 

Conversion Routines 
Built-in Functions 



















Figure 2. PL/I Program Structure 
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Object-Time ouurage Layout 



• the Supervisor program. 



The layout of main storage during execution 
of a PL/ I program is shown in Figure 3. 
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(Aiiccotad only During Execution) 


Ujiper Stdrage 





Figure 3. Object-Time Storage Layout 



The Disk And Tape Operating Systems 

The Disk and Tape Operating Systems (DOS/ 
TOS) are a group of processing programs 
with the control and service programs 
required to maintain continuous operation. 
They are self-contained systems and require 
a minimum of operator intervention. 

The processing programs consist of lan- 
guage translators and service programs. 
The group of processing programs can be 
expanded by adding user-written problem 
programs. 

The system control program — the frame 
work of DOS/TOS — consists of three 
components: 



• the Job Control program, and 

• the Initial Program Loader CIPL). 

These coniDonents are used to load the 
system and to prepare and control the 
execution of all processing and problem 
pro y rams within the systeui. 

The system service programs consist of 
the Linkage Editor and the Librarian. 
These programs are used to bring compiled 
source programs into an executable format 
and to maintain the libraries. 



VA ^11 -VA /I 






Systems, 






rating 



To make full use of DOS/TOS, the user 
should be familiar with CI) the functions 
of the individual system components and (2) 
the interaction of these components. Users 
of the overlay feature should be thoroughly 
familiar with the DOS/TOS Linkage Editor 
program. Users of the label-processing 
facilities should be familiar with DOS/TOS 
data management concepts. This section 
briefly discusses those parts of the DOS/ 
TOS that are of interest to users of the 
PL/I Subset language. 



0\sk/Tt^te Operating Systems 1 
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Figure 4. Schematic Representation of the 
Disk and Tape Operating Systems 



10 



System Control Programs 

The Supervisor handles all hardware inter- 
rupts, causes I/O operations to be per- 
formed, and contains a fetch routine for 
fetching program phases from the core-image 
library. The Supervisor resides in storage 
throughout the execution of all IBM- 
supplied and user-written programs. 

The Job Control program provides job- to- 
job transition within DOS/TOS. It performs 
its functions between job steps and does 
not reside in storage while a problem pro- 
gram is being executed. 

The IPL is of no interest to the PL/I 
programmer. 



System Seryice_Progranis 

The Linkage Editor links all relocatable 
object modules that are produced by the 
language translators, i.e., it assigns 
absolute addresses and resolves cross- 
references between different object modules 
(external symbols). The output of the Lin- 
kage Editor can be either immediately 
executed or incorporated into the core- 
image library. 



The Librarian is a group of programs 
used for maintaining the libraries and pro- 
viding printed and/or punched output from 
these libraries. 

The libraries are: 

the system core-image library 
the system relocatable library 
the system source statement library 
private core- image libraries 
private relocatable libraries 
private source-statement libraries 



The core- image library contains object- 
program phases already processed by the 
Linkage Editor. These programs are ready 
for execution under control of the Supervi- 
sor. The core-image library contains, for 
instance, the system control and service 
programs themselves and the PL/I compiler. 

A DOS system generation option provides 
for the support of private core-image 
libraries on the same type of direct access 
device as the system residence vol\ime. A. 
private core-image library has the same 
format and function as the system core- 
image library on the system residence 
volume. When searcning for a program to be 
loaded, the system loader searches the 
private core-image library first, if 
assigned, and then the system core-image 
library. 



The relocatable library contains object 
modules produced by the language transla- 
tors. Object modules may be preceded by 
Linkage Editor control statements. The 
individual modules contained in the relo- 
catable library are used as input to the 
Linkage Editor. Most of the built-in func- 
tions of PL/I as well as service routines 
required for the execution of PL/I object 
programs are contained in the relocatable 
library. 

The source statement library is not used 
by the PL/I compiler or during object pro- 
gram execution. 



Multipro grammi ng 

DOS and TOS permit the switching of proces- 
sing between one or two foreground programs 
and one background program, in which case 
all programs reside in storage simul- 
taneously. This method increases the total 
throughput since some program may use the 
CPU while another program is waiting for 
input/output. If more than one program 
requires the CPU, the foreground-1 program 
has the highest and the background program 
the lowest priority. The program (s) of 
lower priority are dormant until the 
program (s) of higher priority start (s) 
waiting for a completion of input/output. 

The storage areas - referred to as par- 
titions - assigned to each of the three 
programs are defined at system generation 
time and may be changed by the operator 
between job steps. 

In a DOS system which supports the 
batched- job foreground (MPS=BJF) and priv- 
ate core-image library options, the Linkage 
Editor can execute in either foreground 
partition (as well as the background parti- 
tion) provided a minimum of lOK of storage 
is assigned to the partition. When execut- 
ing in a foreground partition, a private 
core-image library must be assigned. 

In a DOS multiprogramming environment 
described above, the DOS PL/I compiler can 
be executed in any partition in the follow- 
ing manner: 

1. At system generation time, link edit 
the PL/ 1 compiler in the i)ackground 
partition and place it in the system 
core- image library. 

2. Link edit the PL/I compiler in any 
desired foreground partition and place 
it in a private core- image library 
assigned to that partition, 

3. When executing the PL/I compiler in a 
foreground partition, assign the appro- 
priate private core-image library. 
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Logical 
Device 
Address 



Device Referred to 



SYSRDR 



input device from which Job Control statements are read. Not used by PL/'I compiler or obfect programs. 



SYSIPT 



Input device from which the input for the PL/I compiler is read. Can also be referred to by SYSIN. 



SYSIN 



SYSLST 



Input device combining the functions of SYSRDR and SYSIPT. 



Output device used by the Pl/I compiler. The device used is the same as the PL/I stcmdard output device for listing 
(SYSPRINT). (For Pl/l object-time messages refer to PROCEDURE Statement in Appendix H.) 



oi orv,n 



v.ara puncning device usea oy rne ri/i compiler wnen a puncnea cara ooject aecK is specinea. 



SYSOUT 



Output device combining the funcfions of SYSLST and SYSPCH. Cannot be assigned by an ASSGN statement. 



SYSLNK 



Input/output device used by the Linkage Editor and the Pl/I compiler when compiling and subsequent link-editing 
is specified. 



A private core-image library. If such a library is assigned, the output rrom the Linkage Editor is placed here 
either permanently or temporarily. If such a library is not assigned, output from the Linkage Editor goes to the 
system core-image library. 



SYSCLB 



SYSLOG 



SYSOOO 

to 
SYS222 



bh *ft *..« operator wy tus ■ ly ■ ccmpiier und tue Gujecr program. 



SYSLOG is also used when a DISPLAY statement appears in the PL/I program (For PL/I object-time messages refer 
to PROCEDURE Statement in Appendix J.) 



Logical device addresses available to the programmer (programmer logical units as opposed to the remaining units, 
which are also referred to as system logical units). SYSCX)!, SYS002, and SYS003 are used as work file addresses by 
the language processors and the Linkage Editor. They may be used as work file oroutput file addresses, but the user 
must protect his input files from being destroyed by the compiler or Linkage Editor in the case of a compile-and- 
execute or link-and-execute job. For this purpose, he should use the DISPLAY statement with the REPLY option and 
instruct the operator to mount the input file immediateiy before opening the file at execution time if a sufficient 
number of I/O units is not available. 



Figure 5. Logical Device Addresses Used by the PL/I Programmer 



DOS programs compiled by the DOS PL/I 
compiler can be executed in a foreground 
partition, provided the supervisor was 
generated with the option MPS=BJF and a 
minimum of lOK of storage is assigned to 
the partition. PL/I object programs may 
only be executed in batched- job mode. 

Under TOS, the PL/I compiler and the 
Linkage Editor exclusively work in the bac- 
kground partition, TOS programs compiled 
by the PL/I compiler cannot run as fore- 
ground programs. 



I/O Device Ass ig nment 

The I/O devices used during compilation and 
execution are referred to by logical device 
addresses instead of by their physical 
device addresses. Thus, the user may dis- 
regard the physical device assignments of 
the system configuration he uses. Moreov- 
er, if a number of different system confi- 
gurations is used, recompilation of a 
source program is required only if the 
device types (11U2, 25U0, etc.) change. 
The logical device addresses the PL/I pro- 
grammer should know are listed in Figure 5. 

to physical devices 



1. when building the system, 

2. by the operator, or 

3. by means of the ASSGN statement (see 
the section The_ASSGN Statement) . 

If mult i- programming is included in the 
supervisor, independent sets of logical 
device addresses are provided for the back- 
ground area and both foreground areas. 



The Job Control Program 

The Job Control program permits processing 
of batched jobs in background mode. A iob 
is the execution of a problem and consists 
of one or more job steps. A job step is a 
single compilation of an external proce- 
dure, a Linkage Editor run, a Librarian 
run, or the execution of an object program. 



JOB CONTROL STATEMENTS 

The execution of the Job Control program is 
initiated by Job Control statements read 
from SYSRDR. The general format of Job 
Control statements is as follows: 






Name 

Job Control statements are identified 
by two slashes (//) in columns 1 and 2. 
The second slash must be followed by 
one or more blanks. Exceptions are: 

a. The end-of-job statement contains 
/& in columns 1 and 2, 

b. The end-of-data-file statement con- 
tains /* in columns 1 and 2. 

c. The comments statement contains * 
in column 1 and a blank in column 
2, 

Operation 

The entry in the operation field of a 
Job Control statement describes the 
type of operation to be performed. It 
must be followed by one or more blanks. 

Operand 

The operand may be blank or consist of 
one or more entries separated by com- 
mas . Interspersed blanks are not per- 
mitted. The last entry must be fol- 
lowed by one or more blanks unless its 
last character is in column 71. 

Comments 

Comments are permitted anywhere after 

the trailing blank of the operand 

field. 



The ASSGN Statement 

The ASSGN statement is used to assign a 
logical device address to a physical 
device. The format of the ASSGN statement 
is as follows : 



// ASSGN SYSxxx, device-address 



,X'ss' 
,ALT 



SYSxxx is one of the logical devices listed 
in Figure 5 (with the exception of SYSOUT, 
which cannot be assigned by means of ASSGN 
statements). The system permits programmer 
logical units in the range from SYSOOO to 
SYS222. The number of units actually per- 
mitted per partition in a specific instal- 
lation is defined at system generation time 
and normally less than 223. SYSOOO to SYS- 
004 are the minimum provided by the system. 



The following restrictions should be 
observed when re-assigning some of the log- 
ical units: 

1. SYSRDR, SYSIPT, SYSIN, SYSLST, and SYS- 
PCH cannot be assigned to 2311 or 2314 
DASD extents by ASSGN statements. In 
case they are assigned to a 2311 or 
2314 DASD extent either at system 



generation time or by the operator, a 
special version of the PL/I compiler 
that needs a minimum of 12K of storage 
for execution must have been cataloged 
at system generation time. 



SYSLNK must be assigned to the same 
device type as SYSRES for DOS and to a 
magnetic tape drive for TOS. Any re- 
assignments must be made before issuing 
an OPTION statement that contains the 
LINK or CATAL option. 



3. SYSLOG should be assigned to a 1052 
console typewriter. Assignment to a 
printer is possible but degrades the 
system functions and prevents the use 
of the DISPLAY statement with the REPLY 
option. 



4. SYSCLB cannot be temporarily assigned 
(// in columns 1 and 2) . The permanent 
assignment format must be used (ASSGN 
in columns 1 through 5) . 

5. SYSOOl to SYS003 must be assigned to 
the same device type (either magnetic 
tape drives, 2319, 2311, or 2314 DASD 
extents) for the entire duration of a 
compilation. 

Device- address permits three formats: 

X'cuu' where c is the channel number and uu 
the unit number in hexadecimal 
notation. 

UA Unassign, The job is canceled if a 
file attached to this logical unit 
is referred to by one of the I/O 
statements OPEN, CLOSE, GET, PUT, 
READ, WRITE, or REWRITE. 

IGN Indicates the logical unit to be 
unassigned and that all program 
references to the logical device are 
to be ignored. All I/O commands 
issued to the file are ignored. The 
IGN option is not valid for SYSRDR, 
SYSIPT, and SYSIN. For PL/I files, 
the iGN-bit will be checked. And if 
the IGN-bit is on, no OPEN-bit will 
be set. 

X* ss' is the device specification. It is 
used for specifying mode settings for 7- 
track and dual-density 9-track tapes. If 
X'ss* is not specified, the system assumes 
X'90' for 7-track tapes and X'CO* for 9- 
track tapes. The possible specifications 
for X'ss' are listed in Figure 6. 



Note: When creating a 7-track tape file, 
the data-conversion feature must be off. 
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Bytes 

per 

inch 

200 
200 
200 
200 
200 
556 
556 
556 
556 
556 
800 
800 
800 
800 



1600 
800 



-r- 

j Trans- 
I late 
Parity j Featur* 



odd 

even 

even 

odd 

odd 

odd 

even 

even 

odd 

odd 

odd 

even 

even 

odd 

OuQ 



Off 

off 

on 

off 

on 

off 

off 

on 

off 

on 

off 

off 

on 

off 



dual-density 9- 
dual- density 9- 



Convert 
Feature | 

•+ —^ 

on 

off 

off 

off 

off 

on 

off 

off 

off 

off 

on 

off 

off 

off 

I >^£C 

I KJJ.JL 

n_ j-,^ — .—u 

•track 
■track 



ss 

10 
20 
28 
30 
38 
50 
60 
68 
70 
78 
90 
AO 
A.8 
BO 

no 
oo 

/-<A 

CO 
C8 

U X i J 

Figure 6. Possible Specifications for 
X'ss' in the ASSGN Statement 

ALT indicates an alternate magnetic tape 
unit that is used if the capacity of the 
original unit is reached. The characteris- 
tics of the original and the alternate unit 
must be the same. Multiple alternates may 
be assigned to one logical unit. 

Note; All device assignments made with 
ASSGN statements are reset bet we en jobs to 
the configuration specified at system 
generation time plus any modifications that 
may have been made by the operator. (See 
the section The JOB Statement.) 



The_EXEC_Statement 

The execution of a job step is initiated by 
the statement : 

// EXEC name 

Name is the name of the first phase of the 
program to be fetched from the core-image 
library and to be executed. Therefore, 
execution of a PL/I compilation would be 
initiated by the statement 

// EXEC PL/ I 

The name must be omitted if a program 
linked in the previous job step of the same 
job is to be executed immediately after the 
link operation. 

Tbe_JOB_Statement 

Each job begins with the statement: 

// JOB job-name 



Job-name is a user- defined name of 1 to 
characters. 



Note: The JOB statement cancels all pre- 
viously issued OPTION and ASSGN statements, 



The LISTIO Statement 

The LISTIO statement is used to obtain a 
listing of the I/O assignments- The format 
of this statement is 

// LISTIO 

with one of the operands listed in Figure 
7. The listing is produced on SYSLST. The 
xJLS «,jLng varxes accoruing to tue operanu. 
i: or roagne cic uape unxus, pnysicax unius are 
listed with current device specification. 



r T 

I Operand I Causes the Listing of 



SYS 

I- 

PROG 



H 



ALL 



SYSxxx 



UNITS 



DOWN 



UA 



the physical units assigned to 
all system logical units. 

the physical units assigned to 
all background programmer logical 
units. 



the physical units assigned to 
all logical units. 



the physical units assigned to 
the specified logical unit. 



the logical units assigned to all 
physical units. 



all physical units specified as 
inoperative. 



all physical units not currently 
assigned to a logical unit. 



X' cuu' I the logical units assigned to the 
specified physical unit. 



Figure 7. Operands of LISTIO Statement and 
Corresponding Actions 



The MTC Statement 

The MTC statement is used to control opera- 
tions on logical units assigned to magnetic 
tapes. The format of the MTC statement is 

// MTC op- code, SYSxxx [,nn] 



For further details refer to the section 
Multi-File Volumes and Backwards Files. 



lU 



The OPTION Statement 

The OPTION statement is used to specify 
options for the compilation of PL/I source 
programs. Its format is 

// OPTION optionl [, option21 . 

If this statement is omitted, a set of 
standard options defined at system genera- 
tion time will apply. If more than one 
OPTION statement is issued in one job, all 
further OPTION statements change only those 
options that are respecified. All other 
options will remain unchanged. 

All options specified in the OPTION sta- 
tement are canceled when a new JOB state- 



ment is read. (See the section The JO B 
Statement . ) 



The options LINK and CATAL are canceled 



1. if severe or disastrous errors have 
been detected during a PL/ I 
compilation. 



2. after a new EXEC statement has been 
executed. 



The options that may be used by the PL/ I 
programmer are listed in Figure 8. 



Option 


Function 


LOG 


Causes all Job Control statements to be listed on SYSLST. 


NOLOG 


Suppresses the LOG option. 


DUMP 


Causes the contents of core storage and registers to be listed on SYSLST in case of an abnormal termination of the fob. 


NODUMP 


Suppresses the DUMP option. 


LINK 


Causes the compiled PL/I program to be written on SYSLNK for later processing by the Linkage Editor. This option, if 
used, must precede all other Linkage Editor control statements, if any. 


NOLINK 


Suppresses the LINK option. The LINK option is also suppressed if a serious or disastrous error is detected during 
compilation of a PL/I source program or if an EXEC statement with a blank operand field is read. 


CATAL 


Causes the LINK option to be set. In addition, it causes the cataloging of a phase or program into the core-image 
library after either a /& or a // EXEC MAINT statement has been read. 


DECK 


Causes the PL/I compiler to punch an object deck if no disastrous compile-time error has been detected. 


NODECK 


Suppresses the DECK option. 


LIST 


Causes the Pl/I compiler to list the source program on SYSLST. 


NOLIST 


Suppresses the LIST option. 


LISTX 


Causes the PL/I compiler to list the object program on SYSLST. 


NOLISTX 


Suppresses the LISTX option. 


SYM 


Causes the Pl/I to list the symbol table, the block table, the offset table, and the external symbol table on SYSLST. 


NOSYM 


Suppresses the SYM option. 


ERRS 


Causes the PL/I compiler to list all detected errors on SYSLST. 


NOERRS 


Suppresses the ERRS option. 


XREF 


Causes the Pl/I compiler to write a cross-reference listing on SYSLST. 


NOXREF 


Suppresses the XREF option. 


48C 


Informs the Pl/I compiler that source programs are written in the 48-character set in EBCDIC notation. (No provision 
has been made for BCDIC and ASCII character sets.) 


60C 


Informs the PL/I compiler that source programs are written in 60-character set in EBCDIC notation. 


MINSYS 
CTOS only) 


Causes the Linkage Editor to produce minimum-size modules for later runs on systems with a background program 
area smaller than 24K, when link-editing on systems with a larger background program area. 



Figure 8. Operands Used in the OPTION Statement 
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lh§_?^5ISE_Statement eight bits may be tested by problem pro- 

grams at execution time. 

The PAUSE statement can be used to stop 

batched-mode processing in order to save The DOS FL/I compiler checks bit of 

output files produced by a previously the UPSI byte; the other bits are ingored. 

executed program. Its format is 

If bit is on (1) during compilation, 

// PAUSE comments Librarian and Linkage Editor statements are 

produced to permit to compile and catalog 
The comments are printed on SYSLOG (pro- in one job step into the relocatable 

vided SYSLOG has been assigned) to indicate library. Bit should be off (0) if cata- 

the action to be taken by the operator. loging into the relocatable library is not 

desired. For further details on cataloging 

The RESET Statement refer to the section Catalogin g into t he 

Relocatable Lib rar y . 

The RESET statement resets I/O assignments ^ 

to the standard assignments. The standard 

assignments are those specified at system The End-gf;"Data-File_Staternent 

generation time plus any modifications made ^ 

by the operator fay means of an ASSGN com- The end-of -data-file statement (/* in 

mand (as opposed to using an ASSGN control columns 1 and 2) serves as a delimiter for 

statement) without the TEMP option. The the input read from SYSIPT, Therefore, 

format of the RESET statement is: PL/I programs must be terminated by an end- 

of-data-file statement. This statement is 

// RESET also recognized on the programmer logical 

units that are assigned to a card reader. 
This causes the ENDFILE condition to be 
raised for a PL/I input file. 



with one of the operands SYS, PROG, ALL, 
SYSxxx. The meaning of the individual 
operands is described below. 



SYS resets all system logical units to 
their standard assignments. 

PROG resets all programmer logical units to 
their standard assignments. 

ALL resets all programmer and system logic- 
al units to their standard assignments. 

SYSxxx resets the specified logical unit to 
its standard assignment. 

The UPSI Statement 

This statement (User Program Switch Indica- 
tors) allows the user to set program 
switches that can be tested much the same 
as sense switches or lights used on other 
machines. The UPSI statement has the fol- 
lowing format: 

// UPSI nnnnnnnn 

The operand consists of one to eight 
characters of 0, 1, or X. Positions con- 
taining are set to 0. Positions contain- 
ing 1 are set to 1. Positions containing X 
remain unchanged. Unspecified rightmost 
positions are assumed to be X. 

Job Control clears the UPSI byte to 
zeros before reading control statements for 
each job. When Job Control reads the UPSI 
statement, it sets or ignores the bits of 
the UPSI byte in the communication region. 
Left to right in the UPSI statement, the 
digits correspond to bits through 7 in 
the UPSI byte. Any combination of the 



The En d-of-Job Statemen t 

The end-of-job statement (/6 in columns 1 
and 2) indicates that a job has been com- 
pleted. If this statement is omitted, the 
Job Control program may skip the next job 
stacked on SYSRDR and/or SYSIPT. If SYSRDR 
and SYSIPT are different units, the end-of- 
job statement must appear on both. 

The Comments S tatemen t 

A special comments statement (* in column 1 
and blank in column 2, followed by the 
desired comments) is available for longer 
messages. The comments are printed on SYS- 
LOG,, but no halt is caused by this 
statement. 

File Label Job Control Statements 

For all Job Control statements referring to 
disk and tape .file labels see the section 
Fil e_Labe 1 s . 

TheJPROCESS Statement 

The PROCESS statement allows the programmer 
to specify compile-time options. More than 
one card may be used per external 
procedure. 

General format: 

* PROCESS option t, option J... 

or 

+ PROCESS option [, option]... 
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General rules: 



b. STMT, NOSTMT 



1. The cards have to precede the PL/ I 
source program. They must, however, 
follow the // EXEC PL/I statement. 

2. The card has to start either with an 
asterisk or with a plus sign in column 
one, followed by one or more blanks. 
If the plus sign is used it is treated 
as an asterisk. The option list may 
not extend beyond column 71. 

3. The options in the PROCESS statement 
override job-control options or any 
other options encountered in previous 
PROCESS statements. 

The options that can appear in the 
operand field of a PROCESS card are: 

1. Options supported by Job Control: 



DECK 


NOSYM 


NODECK 


ERRS 


LIST 


NOERRS 


NOLI ST 


XREF 


LISTX 


NOXREF 


NOLISTX 


48C 


SYM 


60C 



A. description of the above options is 
given in Figure 8 in the section The 
Job Control_Frogram , 



Options not supported by Job Control 
a, OPT, NOOPT 
OPT 



causes the optimization of 
compiled code. 



NOOPT suppresses the OPT option. 

The default is OPT. 

Optimization implies the deletion 
of as much code as the compiler can 
diagnose as redundant. 

If the option OPT is used, sequen- 
tial assignment statements for the 
same variable (e.g., A=l; B=X; A.=3; 
are optimized by deletion of the 
first assignment to A because there 
is no reference to A between the 
two assignments to A. 

If the contents of 'A* were 
required between the two assign- 
ments (e.g., were used as control 
values in the event of an interrupt 
such as SIZE, CONVERSION, etc.) the 
assignment statement would have to 
be labeled because labeling a sta- 
tement resets the internal optimi- 
zation control. 



STMT causes statement numbers to 
be printed with object time 
diagnostics. 

NOSTMT suppresses the STMT option. 

The default is NOSTMT. 

Note: In a program consisting of 
several external procedures, STMT 
must always have been specified for 
the first external procedure that 
is stored on SYSLNK if the object- 
time diagnostic messages for any of 
the external procedures of the pro- 
gram are to include the numbers of 
the source statements causing 
errors. If, for example, STMT is 
specified only for the second 
external procedure stored on SYS- 
LNK, statement numbers are not 
printed for this procedure. In 
addition, STMT must also have been 
specified for the first external 
procedure. 



LISTO, NOLISTO 

LISTO causes the statement num- 
bers to be listed and the 
offset of the first byte 
used after these statements 
to be printed. 

NOLISTO suppresses the LISTO 
option. 

The default is NOLISTO, 

Note: LISTO overrides LISTX, i.e., 
if LISTO and LISTX are specified,, 
the LISTX option is ignored. 



COMPILATION UNDER DOS/TOS CONTROL 

If a single PL/I source module is to be 
compiled under DOS/TOS control, the card 
sequence should be as follows: 



// JOB 
// OPTION 
// EXEC 



/* 
/g 



job-name 

DECK, LIST, NOSYM,60C see note 1 

PL/I 

PL/I source module 



see note 2 



Not e _1: This statement causes the PL/I 
compiler to punch an object module on SYS- 
PCH and to list the source program on SYS- 
LST. The listing of source module symbols 
is suppressed. The source program is writ- 
ten in the 60-character set. LOG, DUMP, 
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LISTX, and ERRS are assumed to have been 
established as standard options at system 
generation time. 

Note__2j^ ?^nother /& card must be read from 
SYSIPT if SYSRDR and SYSIPT do not refer to 
the same input device. 



Deck on SYSRDR 



h 

i // JOB MYJ OB } 

j// OPTION DECK,48C | 

|// ASSGN SYSIPT,X'271\X'50' j 

I* PLEASE MOUNT REEL 4711 ON UNIT 271 j 

[// PAUSE PROCEED j 

|// EXEC PL/I I 

|// EXEC PL/I I 

|// EXEC PL/I I 

|/S ! 

I Records on SYSIPT ! 

j. ^ 

I First PL/ I source module | 

I 
Second PL/I source module | 

I 
Third FL/± source module ! 



\/* 

I 
|/* 

I 

|/* 

|/g 

L 



Figure 9. Coding for a Job Consisting of 
three PL/I Compilations 

ASSGN statements to change the assign- 
ment of logical device addresses for this 
job may be placed anywhere between the JOB 
and the EXEC statement. Assignments for 
3Y3LNK must not be changed after OPTION 
LINK has been specified. 

Figure 9 shows the coding for a job con- 
sisting of three PL/I compilations. SYSRDR 
and SYSIPT are assumed to refer to dif- 
ferent input devices. SYSIPT is assumed to 
be a 7 -track tape drive. 

Since a job step comprises only one 
single compilation, an EXEC statement as 
well as a /* statement is required for the 
compilation of each source module (external 
procedure) , 

Main storage reguirements fo r compilation; 
In the background partition, without system 
files on disk: 

lOK plus supervisor area required 
for the compiler version used 

In the background partition, with system 
files on disk: 

12K plus supervisor area required 
for the compiler version used 

In the foreground partition, without system 
files on disk: 



lOK plus foreground save area required 
for the compiler version used 

In the foreground partition, with system 
files on disk: 

12K plus foreground save area required 
for the compiler version used 



.^ The Linkage Editor Program 



The Linkage Editor program relocates the 
object modules produced by the PL/I compil- 
er into an absolute object program. 
Modules retrieved from the relocatable 
library may be incorporated into the object 
program during the Linkage Editor run. 
Programs written in Assembler language and 
assembled by means of the DOS/TOS Assembler 
may also be incorporated. For details on 
the communication with programs written in 
Assembler language refer to the section 
Linkage Conventions. The object program 
produced by the Linkage Editor may either 
be executed by using the EXEC statement 
with a blank operand or be incorporated 



Xiico y,LiQ core-ima> 



^ -i Ki^o-i'T 



If a Linkage Editor run is desired, the 
first Linkage Editor control statement and 
the first EXEC statement must be preceded 
by an OPTION statement with either the LINK 
or the CATAL option. 

In a TOS or DOS non- multiprogramming 
system, the Linkage Editor can run in the 
background pa;rtition only. In a DOS multi- 
programiTiing system which also supports the 
private core- image library option, the Lin- 
kage Editor can run in either foreground 
partition (as well as the background) pro- 
vided a minimum of lOK of main storage and 
a private core- image library is assigned. 



LINKAGE EDITOR CONTROL STATEMENTS 

The execution of the Linkage Editor program 
is initiated by Linkage Editor control sta- 
tements read from SYSRDR, The general for- 
mat of Linkage Editor control statements is 
similar to that of the Job Control state- 
ments, except that Linkage Editor control 
statements have a blank in column 1 instead 
of // in columns 1 and 2. 



The Linkage Editor program uses the fol- 
lowing four control statements: 

• the PHASE statement, 

• the INCLUDE statement, 

• the ENTRY statement, and 

• the ACTION statement. 



18 



The exact format of these statements is 
given in those parts of this section where 
their application is described. 

The RCTIpN Statement 

This is an optional statement for directing 
the Linkage Editor. If ACTION statements 
are issued to the Linkage Editor, they must 
precede all other input to the Linkage Edi- 
tor on SYSLNK. This can be ensured by 
placing the ACTION statement (s) immediately 
after the OPTION statement with the operand 
LINK or CATAL. The format of the ACTION 
statement is: 



ACTION 



operand 



The following operands are of interest 
to the PL/I user: 

BG The program is link- edited to 
Fl execute in the specified 
F2 partition. The start address of 
the appropriate partition is 
assumed to be the end of the 
Supervisor (for background) or the 
address of the specified fore- 
ground partition allocated at link 
edit time. Only one of these 
operands may be specified for one 
link-edit step. Ose of these 
operands allows the program to be 
link-edited to execute in a parti- 
tion other than the one in which 
the link-edit function is taking 
place. 

In the absence of these operands 
the program is link-edited to 
execute in the partition in which 
link-editing is taking place, 
(These operands are not available 
in TOS) . 

NOMAP Suppresses listing of the Linkage 
Editor storage map on SYSLST. 
Diagnostics are written on SYSLOG. 

CANCEL The job is canceled if any error 
is detected during link-editing. 

More than one ACTION statement may be 
issued for one link-editing step. 

The PHASE Statement 

If the program consists of more than one 
phase or if the program is to be cataloged, 
each phase to be link-edited must be pre- 
ceded by a PHASE statement of the following 
format: 

PHASE phase-name, origin 

Phase-name is a symbol consisting of 1 to 8 
characters, the first of which must be 
alphabetic but should not be a $ sign. In 



case of multi-phase programs,, the phase- 
name must be longer than four characters 
and the first four characters must be 
identical for all phase names of that pro- 
gram. Different programs must differ in 
the first four characters of their phase 
name(s) in order to avoid incorrect storage 
allocation. (See the section P r ocess ing of 
Overlays by the Linkage Edit or. ) 

Origin indicates to the Linkage Editor the 
begin address of this specific phase. An 
asterisk may be used as an origin specifi- 
cation to indicate that this phase is to 
follow either 

the previous phase or the Supervisor at 
the next double-word boundary (for back- 
ground programs) or the start of the 
partition (for foreground programs). 

This simple format of the PHASE state- 
ment covers all normal applications in the 
background partition. For the format of 
the phase origin in overlay structures 
refer to the section Overlay. 

Three methods are available for link- 
editing foreground programs : 

1. Using the statement ACTION Fn. In this 
case, the same set of PHASE statements 
may be used as for background programs. 

2. Using the operand format F+address of 
the PHASE statement for the origin of 
the first (or only) phase. 

address is the absolute address of the 
foreground area in which the link- 
edited program is to be executed. It 
may be specified by a hexadecimal numb- 
er of four to six digits (X'hhhhhh') or 
by a decimal number of five to eight 
digits (dddddddd) or in the form nnnnK, 
where nnnn is two to four digits and K 
equals 1024. For example, an origin 
may be specified as F+X*8000' or F+ 
32768 or F+32K. 

3. Executing the link- edit function in the 
desired foreground partition. In this 
case, the same set of PHASE statements 
may be used as for background programs. 

For each method, a foreground save area 
is created at the specified address. The 
(first) phase starts at the first double- 
word boundary following this save area. 
The space allocated to a foreground program 
by the Linkage Editor plus sufficient space 
following the end of the program for dynam- 
ic allocation of PL/I automatic storage 
must be allocated at execution time to the 
appropriate foreground partition. 

Programs compiled by the PL/I compiler 
and PL/ I library routines are not 
self -relocating. 
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Note: The autolink feature of the Linkage 
Editor is required to include routines from 
the relocatable library that are to be 
linked with the object modules compiled by 
the PL/I compiler. Therefore, the option 
NOAUTO of the PHASE or ACTION statement 
must never be used. 



INCLUDING OBJECT MODULES INTO THE OBJECT 

The appropriate object modules can be inco- 
rporated into the object program by: 

• compilation, 

• including object card decks, 

• includin'^ ob"'ect modules from the relo- 
catable library, or 

• using the autolink feature. 

To have the source module compiled and the 
output written on SYSLNK, the card sequence 
must be as follows: 

// EXEC PL/I 

• . . . PL/I source module 

• « • « 

/* 

If SYSRDR and SYSIPT refer to different 
input devices, the PL/I source module and 
tne /* card must be read from SYSIPT. 

Processing by the Linkage Editor and 
execution is suppressed in case severe or 
disastrous programming errors are detected 
during compilation. 

Source modioles written in Assembler lan- 
guage may be added in the same manner by 
using the statement // EXEC ASSEMBLY for 
calling the Assembler. For details on the 
communication with programs written in 
Assembler language refer to the section 
Linkage Conventions . 

Including Object card Decks 

To include one or more object card decks 
into the object program, the required con- 
trol cards as well as the sequence in which 
they must be read from SYSIPT or SYSRDR, 
respectively, are shown in Figure 10. 

Note: The INCLUDE card, when used for this 
application, must have the following 
format: 

INCLUDE preceded and followed by blanks 
only 



Cards 



-T 1 

I Read from | 



INCLUDE 



one or more ob- 
ject modules 



I/* 

I ■ 

L 



SYSRDR 
SYSIPT 

I QVQTTJfT 



riguxe iu . xriciaQj.ny uujecr. uara DecKs 



Including Qhi!6gt_Modules_from the 
RelocatableLibrary 

An INCLUDE statement must be read from SYS- 
RDR for each module to be incorporated into 

Tine v/jjj\i<^i_ ^ji.^j'j i.a.111 j.i.yjii\ v-xic: j-cxvjv^oi ociJJ J.C 

library. When used for this application, 
the INCLUDE statement must have the format: 

INCLUDE module-name 



Using th e Autolink Feature 

If some references to external names remain 
unresolved after all modules have been read 
in from SYSLNK, SYSIPT, and/or from the 
relocatable library, the autolink feature 
of the Linkage Editor searches the relocat- 
able library for module names identical to 
the unresolved names and includes the 
corresponding modules into the object 
program. 

Private Relocatable Library un der DOS 

Cataloging and including of relocatable 
modules may be performed by means of a 
private relocatable library. For DOS, the 
private relocatable library resides on an 
extra 1316 disk pack. The 2311 disk drive 
on which this pack is mounted has the log- 
ical device address SYSRLB. 

For including modules, the DOS Linkage 
Editor first searches the pack assigned to 
SYSRLB and, if the requested module is not 
found there or if SYSRLB is not assigned, 
it searches the relocatable library on the 
system residence pack. 

If SYSRLB is assigned, relocatable 
modules are cataloged into the private 
relocatable library. Otherwise, they are 
cataloged into the system residence pack. 

For creating private relocatable 
libraries refer to the SRL publicat .on IBM 

Si;^tem/360j; Disk_Operating_SYStem, Sys tein 

Control and_System_Seryice Programs , Or der 
No. GC2U-5036. 

For private relocatable libraries under 
TOS see Special Considerations on TOS. 
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The_ENTRY_Staten!ent 

The card input to the Linkage Editor may be 
delimited by an ENTRY statement of the fol- 
lowing format: 

ENTRY [name] 

Name is the external name of the entry 
point used. The entry point must be a pri- 
mary or secondary entry of the external 
procedure that has the option MAIN. If the 
primary entry point of the MAIN procedure 
is used, the name may be omitted. 

If no ENTRY statement is issued, ENTRY 
with a blank operand is assumed. 

Note: If modules written in Assembler lan- 
guage are to be incorporated into the 
object program, the Assembler END statement 
should have a blank operand field in order 
to avoid confusion of entry points. 

Errors Due to Multiple Seco n dary E n try 
Points 

For each file specified in the source pro- 
gram, the compiler generates a separate DTP 
table which includes the names of the I/O 
modules to be called. 

Sometimes different I/O modules have 
identical secondary entry names. For 
example, if a program uses ISAM files and 
ADDBUFF is specified for one of these files 
and INDEXAREA for another, then the secon- 
dary entry point IJHAARZZ occurs in modules 
IJHAARCZ and IJHAARZP, which are provided 
for these two files. In a case like this, 
the linkage editor error message 214 3 I 
(Content of statement in error) is 
generated during link-editing. Inspite of 
this error message, the program may execute 
correctly. 

There is no way of determining before- 
hand whether or not a program with linkage 
error message 21U3I will execute correctly. 
To make sure that the correct module is 
linked to the program, the following should 
be done: 

Message 21U3I gives the multiple entry name 
in print positions 64 through 71 and the 
name of the module that was linked to the 
program in print positions 39 through 46. 
The linkage editor output listing repeats, 
in the LABEL column, the multiple secondary 
entry name and also lists the name of the 
other module in which this entry name 
occurs. 

In a new linkage-editor run, now, a 
supersetted I/O module must be specified 
for inclusion in the program. This super- 
setted module will contain the individual 
modules whose inclusion caused the error 



message 21431 to be generated, The name of 
the supersetted module is found as follows: 



Assume that two ISAM files have been 
specified, one with the ENVIRONMENT attri- 
bute ADDBUFF and another with the ENVIRON- 
MENT attribute INDEXAREA. In this example, 
the linkage editor generates message 21431 
with the multiple secondary name IJHAARZZ 
printed in positions 64 through 71 and the 
name of the I/O module in which this secon- 
dary entry name occurs (IJHAARZP, which is 
provided for an ISAM file with the ADDBUFF 
option) printed in positions 39 through 46. 



In the linkage editor output listing, 
the secondary entry name IJHAARZZ appears 
in the column LABEL under the associated 
CSECT name (IJHAARCZ, the name of the 
module which is provided for an ISAM file 
with the INDEXAREA option) . 



Figure 11 bolow shows how to build the 
name of a supersetted I/O module; this name 
should then be specified in an INCLUDE card 
and inserted before // EXEC LNKEDT 
statement: 



INCLUDE IJHAARCP 
// EXEC LNKEDT 





Name of 

I/O module 

included 


Name of 
supersetted 
I/O module 


ADDBUF 
specified 

INDEXAREA 
specified 


IJHAARZP 
IJHAARCZ 

V 


IJHAARCP 




"■ 


Where the characters of the module names are identical, these 
characters are used in the sanie positions of the name for the 
supersetted module. 

Where the characters of the module names differ, the lowest 
character is used in the corresponding position of the name for 
the supersetted module. 



Figure 11. Building the Name of a Super- 
setted I/O Module 



Errors Due to_ Mul ti ple C SECT Names 

Different user-written or PL/I modules to 
be linked to a program by the linkage edi- 
tor may have identical CSECT names, as 
shown in Figure 12. 
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SAMPLE COMPILATION 



imcduie ncmes in reiocotobie library j 



ENTRX: 
ENTRY: 



CSBCT names 
used in cors- 
imqge iibrary 
where program 
is stored 



ENTRX: 
ENTRY: 




/* 

// LXEC LNKEDT 
/& 



■/ JOB 
PROCA; 



PROCB: 



/* 

// EXEC LNKEDT 

/& 



Figure 12, Multiple CSECT Names 



The modules shown in Figure 12 may have 
completely different code, or the code of 
the two modules may be identical to a cer- 
tain point,, with one of the modules having 
one or more additional entry points (as in 
Figure 12) . 



A linkage-edit time, now, the linkage 
editor fetches the required module from the 
relocatable area, where the modules are 
stored under different names, and checks 
whether the corresponding CSECT name is 
already on SYSLNK. If the CSECT name is 
already contained in SYSLNK the second 
iTiOdule with the identical CSECT name (but 
the different module name) is not linked. 
If a request to any additional entry (ENTRV 
or ENTRZ) exists, an error message is 
issued, but link- editing is continued. At 
execution time, an error will result. 



To avoid errors due to multiple CSECT 
names, the modules required must be 
included in the appropriate external proce- 
dure by means of an INCLUDE statement as 
shown in Figure 12. 



The example shown in Figure 13 illustrates 
a combination of all three possibilities to 
build an object program. Four modules plus 
the appropriate library subroutines are to 
be combined into an object program, which 
is to be executed upon completion of the 
compilation. The example is based on the 
following assumptions: 

1. 0ns module (A) is a PL/I source itiodule. 

2. Two modules (PI, P2) have been pre- 
viously compiled and punched. 

3. One module (R) is contained in the 
relocatable library. 

4=s A listin" of the source program and the 
svmnol table is required for module A« 

5. A is the entry point to be used. 

6. The job is being executed in the back- 
ground partition. 



Not e: The numbers at the left in Figure 13 
are for reference purposes only; they are 
not part of the coding. 



7 

8 

9 

10 



11 
12 



// JOB N0123U 

// OPTION LINK, SYMj LIST 

PHASE EXAMPLE,* 
// EXEC PL/I 

A: PROCEDURE OPTIONS (MAIN) ; 



END /*A*/; 
/♦ 

INCLUDE 

deck PI 

deck P2 

/♦ 

INCLUDE R 

ENTRY 
// EXEC LNKEDT 
// EXEC 

data 

/* 
/S 



Figure 13. Sample Compilation 



Explanatio n 

1 Furnishes the Communication Region of 
the Supervisor with the name of the job. 
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Specifies the compiler options SYM and 
LIST and enables the PL/I compiler and 
Job Control to write or copy the output 
on SYSLNK for later processing by the 
Linkage Editor. 



The PH?^SE statement precedes all modules 
to be processed by the Linkage Editor. 
The asterisk indicates that the program 
is to be loaded immediately following 
the Supervisor. 



ii Calls the PL/I compiler. 



PL/I source program, A (the name of the 
MAIN procedure) is the primary entry 
point. 



Causes the subsequent modules PI and P2 
to be copied onto SYSLNK. 



7 This statement is copied onto SYSLNK. 
When encountered by the Linkage Editor, 
the module R is fetched from the relo- 
catable library and incorporated. 

8 Delimits the input to the Linkage Edi- 
tor. The blank operand causes the pri- 
mary entry point A to be entered by Job 
Control at execution time. 

9 Calls the Linkage Editor to produce the 
object program. The names of all 
modules called by A, PI, P2, and R must 
be names of modules contained in the 
relocatable library. These modules are 
automatically incorporated by the auto- 
link feature of the Linkage Editor. 

10 Causes Job Control to fetch the execut- 
able object program and transfers con- 
trol to A for execution. 

11 The end-of-data-file statement delimits 
the input data. If the file name is 
explicitly declared, this statement may 
be tested by means of an ON ENDFILE 
statement. 

12 End-of-job statement. In case of an 
abnormal termination of the job. Job 
Control skips all input up to this 
statement. 

Assumed that all input to be read from 
SYSIPT has been loaded onto a 7-track tape 
reel and that SYSIPT is assigned to the 
tape drive whose physical address is 281, 
the input from SYSRDR and SYSIPT for the 
above example is as shown in Figure 14. 



Cards read from SYSRDR 



13|// 

|// 

I 

|// 



|// 

14 I /S 
X 



JOB 

ASSGN 

OPTION 

PHASE 

EXEC 

INCLUDE 

INCLUDE 

ENTRY 

EXEC 

EXEC 



N01234 

SYSIPT, X'281' ,X'90' 

LINK, SYM, LIST 

EXAMPLE,* 

PL/ 1 



R 



LNKEDT 



Figure 14, 



Explanation 



Control Cards and Input Units 
for Deck Shown in Figure 13 
(Part 1 of 2) 



13 SYSIPT is assigned to a 7-track tape 

drive. (The assignment differs from the 
installation standard.) 



14 /6 must appear on both SYSRDR and 
SYSIPT, 



r — T 
I 

I- 



Cards read from SYSIPT 

A: PROCEDURE OPTIONS (MAIN) ; 



^ 



I/* 



/* 



/* 
/g 



END /*A*/; 

, * . deck PI 
, . . deck P2 

data 



14 

L X J 

Figure 14, Control Cards and Input Units 
for Deck Shown in Figure 13 
(Part 2 of 2) 

To execute the same job in a foreground 
partition with a private core- image library 
on a disk unit whose physical address is 
191, the statement 

ASSGN SYSCLB,X'191' 

must follow the JOB card. In this case, 
the program is link-edited to be loaded at 
the start of the foreground partition. 
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Cataloging 



Cataloging of frequently used program 
phases or object modules into one of the 
DQS/TOS libraries (^reatlv reduces the time 
required for card reading and/or Linkage 
Editor processing. Object modules may be 
cataloged into the relocatable library. 
Executable programs already processed by 
the Linkage Editor may be cataloged into 
the system or, if assigned, a private core- 
image library. 

The name of a phase or module must be 
unique for each library. If phases or 



Lllvy^Jl^JL ' 



. 1 n^at^ 



a^^4- -1 TT£i 1 -1 V\vo-r"t 



and having the same name is automatically 
deleted. This necessitates some naming 
conventions for each installation in order 
to prevent a user from deleting programs 
that are either part of the system or cata- 
loged into the library by other programmers 
using the same installation. Core- image 
library phase names starting with $ as well 
as relocatable library module names start- 
ing with IJ are names of system programs. 
For this reason, the user should be very 
careful when cataloging phases or modules 
the names of which start with the above 
characters. 

The Library routine that handles cata- 
loging and deleting is called by the Job 
Control statement // EXEC kAINT. 



Cataloging Into The Core-Image Library 

If a program is to be cataloged into the 
core-image library, the statement // OPTION 
with the CATAL option must be given prior 
to Linkage Editor processing, i.e., this 
statement must precede the first PHASE card 
of the program to be cataloged in case of 
compile-and-link runs. Dpon successful 
completion of Linkage Editor processing the 
program is then automatically cataloged 
when an // EXEC LNKEDT and /£ card is read. 
(Note that no // EXEC statement without 
name must precede the // EXEC LNKEDT or /& 
statement in this job.) No further catalog 
control statements are required- 

If a private core-image library is 
assigned, the program is cataloged into 
that library rather than into the system 
core-image library. 

Note: An error may occur if a phase exists 
in the core- image library whose name starts 
with the same four characters as the pro- 
gram to be cataloged (see the publication 
IBM System/3 SODisk Operating System^, Sys- 



tem Control and System Servi ce Program s, 
Order No. GC24-5036), 

Programs or phases that are no longer 
required in the core-image library may be 
uexeteu by using the DELETC statement, the 
two possible formats of which are as 
follows : 

DELETC phasel[,phase2] .. . 
DELETC prgl.ALL[,prg2.ALL],.. 

The first format is used to delete 



oa (-•)-> or-iOi-^T -Ft 



■J-'hp pamQ r\-f nriQ 



phase to be deleted. The second format is 
used to delete entire programs. Since the 
first four characters of all phase names of 
any program are identical, the entire pro- 
gram is deleted if these four characters 
are specified, prgl, prg2, etc., must 
therefore be exactly four characters long. 



Cataloging Into The Relocatable Library 

Each card deck to be cataloged into the 
relocatable library must be preceded by the 
control statement 



•Cniaijjrc mcauie-name I , v.mj 

The module specified by the operand 
module- name is then incorporated into the 
relocatable library. Cataloging stops when 
the END card of the module has been cata- 
loged. The module may be preceded but not 
followed by Linkage Editor control 
statements. 

v^m specifies the change level at which 
the module is to be cataloged, v may be 
any decimal number from through 127. m 
may be any decimal number from through 
255. A change level of 0,0 is assumed if 
this operand is omitted. 

Compilation of a PL/I source module may 
result in two object modules. (The first 
one will be referred to as file module and 
the second one as procedure module in this 
section.) The file module is produced for 
all of the file declarations (except file 
name parameters) contained in the source 
module. The procedure module is produced 
for the source module itself. Note that 
each individual object module requires a 
separate CATALR statement for cataloging. 
The file module may be cataloged under any 
of the file names. 
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The DOS PL/I compiler facilitates cata- 
loging into the relocatable library by 
optionally producing control statements on 
SYSPCH. If bit of the OPSI byte (see the 
section The UPSI Statement) is on during 
compilation, the following output is 
generated on SYSPCH depending on whether or 
not a file module is generated with the 
external procedure: 



with file module 

CATR.LR Fname 

file module 
CATALR name 
INCLUDE Fname 

procedure module 



without file module 

CATALR name 

pri^cedure module 



name is the primary entry point of the 
external procedure. Fname means that the 
name of the external procedure, immediately 
preceded by the character F, is used as the 
name of the file module. The INCLUDE sta- 
tement is generated to have the file module 
automatically included with the procedure 
module. 

There is no automatic catalog feature 
for compile-and-catalog into the relocat- 
able library. However, if a sufficient 
r.umber of tape drives is available, it is 
recommended to assign SYSPCH to a magnetic 
tape drive and to reassign the same drive 
to SYSIPT for the catalog step, thus eli- 
minating unnecessary card handling. 

The following example shows what control 
statements are required for compile-and- 
catalog into the relocatable library: 



// JOB COMPILE AND CATALOG 

* INTO THE RELOCATABLE LIBRARY 

// OPTION SYM,LISTX,DECK 

// UPSI 1 

// ASSGN SYSPCH, X' 182* 

// MTC RE W, SYSPCH 

// EXEC PL/ I 



PL/I source program 



/* 




3 // MTC 


WTM, SYSPCH 


3 // MTC 


REW, SYSPCH 


3 // RESET 


SYSPCH 


H // ASSGN 


SYSIPT, X' 182* 


5 // EXEC 


MAI NT 


/& 




Explanation 





1. This statement causes the DOS PL/ I com- 
piler to generate control statements 
that precede the object module (s). 

2. Assigns magnetic tape unit 182 to SYS- 
PCH and positions the tape at the load 
point. 



3. Closes and repositions SYSPCH. (Do not 
use the // CLOSE statement since this 
statement unloads the tape, thus caus- 
ing unnecessary operator action) . 

4. The compiler output is now assigned to 
SYSIPT, 

5. The Librarian is called. The CATALR 
statements cause cataloging into the 
relocatable library. 

Note: The control statements are generated 
only on SYSPCH, not on SYSLNK, Thus,, 
compile-and-catalog into the relocatable 
library does not preclude the LINK and 
CATAL options in the same job. 

The DELETR statement may be used to 
delete either single modules or entire pro- 
grams contained in the relocatable library. 
All modules whose names start with the same 
3-character combination are considered to 
be part of the same program. The two poss- 
ible formats of the control statement are 

DELETR module-namel[,module-name23 ., . 

DELETR prgl.ALL[,prg2.ALL].. . 

The operands prgl, prg2, etc., must con- 
sist of exactly 3 characters. 



Library Maintenance Runs 

Cataloging and deleting for all libraries 
can be done in one single job step. In the 
following example, the program LNCT is 
deleted from the core- image library and the 
modules BCDFIR and BCDSEC are cataloged in 
the same job step. BCDSEC is preceded by a 
PHASE statement that is to be cataloged 
with the module. 



// 


JOB 


CATALOG TWO DECKS, 


* 




SECOND WITH PHASE CARD 


// 


EXEC 


MA INT 




DELETC 


LNCT. ALL 




CATALR 


BCDFIR 




... deck BCDFIR 



CATALR BCDSEC 
PHASE BCDPR2,* 
* THIS STATEMENT IS ALSO CATALOGED 



/* 
/S 



deck BCDSEC 



END OF MAINT. DECK 



The input deck must be followed by an 
end-of-data-file statement if another job 
step within the same job follows the main- 
tenance run. The Librarian control state- 
ments and input decks to be cataloged are 
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read from SYSIPT. (In TOS, Librarian con- 
trol statements are read from SYSRDR. ) 

Examgle fqr_Cataloging_a_Foreground Program 

Two methods are available for cataloging a 
foreground program: 

1. If the program is compiled and link- 
edited in the background, the following 
job stream can be used; 

// JOB CATALFG 

// OPTION CATAL 

1 ACTION F2 

2 PHASE FGPXYZ,* 
// EXEC PL/I 



Special Considerations on TOS 

If TOS is used, phases in the core-iiriage 
and modules in the relocatable library are 
not stored at random locations but in 
alphameric order. Therefore, all phases 
and/or modules to be cataloged must also be 
in alphameric order. Maintenance requests 
for the core-image and the relocatable 
library may be given in the same job step 
but must not be intermixed. Note that a 
maintenance run under TOS control causes 
copying of the full system onto a new 
volume that will be located on SYS002. 
SYSOOl must be assigned to a tape drive for 
intermediate use in this case. 



2, 



PL/ 1 

/♦ 

// ASSGN 

// EXEC 

/g 



source deck 



SYSRLB,X'192' 
LNKEDT 



The ACTION Statement (1) causes the 
Linkage Editor to allocate storage for 
the program in the storage presently 
allocated to the foreground- two parti- 
tion. The PHASE statement (2) gives 
the program the name FGPXYZ. The 
second operand (*) specifies that the 
program is to start n bytes behind the 
location assigned at link- edit time as 
the start address of the foreground- two 
partition (n is the length of a fore- 
ground save area required by the sys- 
tem) . The program to be cataloged is 
compiled in the same job.. The ASSGN 
statement <3) assigns SYSRLB so that 
the Linkage Editor can obtain modules 
to be included by the AUTOLINK feature 
from a private relocatable library. 

If the program is compiled and link- 
edited in the foreground, two changes 
are made to the above job stream: 

a. The ACTION statement is removed 
because the program will be link- 
edited to execute in the foreground 
partition in which the link- edit 
function is taking place. 

b. Th«? statement 



The TOS compiler does not generate 
CATALR statements. However, the user may 
prepare his own CATALR statements and put 
them into the job stream on SYSRDR follow- 
ing // EXEC MAI NT. (In TOS, Librarian con- 
trol statements are read from SYSRDR 
instead of from SYSIPT. ) The file module 
should be given a name equal to one of the 
file names to avoid the use of an INCLUDE 



stateiiiSiiu j.(jx 



including the file module, 



Users needing a large number of relocat- 
able modules should use a p rivate r elo cat- 
able library. Using a private relocatable 
library yields the following advantages: 



1. Only the relocatable library is copied 
during updating. 



2. The performance of INCLUDE and AUTOLINK 
is considerably faster during proces- 
sing by the Linkage Editor. 

During Linkage Editor processing and 
library maintenance, the private relocat- 
able library resides on an additional mag- 
netic tape unit assigned to SYSRLB. A 
private relocatable library is produced by 
preceding the first CATALR or DELETR state- 
ment by the special Librarian statement 
NEWVOL. (The tape reel on SYS002 to accom- 
modate the newly created relocatable 
library must be initialized with a standard 
volume Idbel.) 



ASSGN SYSCLB,X'191' 

is added to assign a private core- 
image library. The program will be 
cataloged in the private core-image 
library. 



If a private relocatable library is to 
be used on TOS, it must contain all modules 
to be included from the relocatable library 
because SYSRLB and the relocatable library 
on the system's resident library are never 
searched both. 



26 



Data Files 



A file is a set of data stored on an 
external storage medium. Its purpose is 
either one or a combination of the 
following: 



• To provide the program with the required 
input. 

• To store intermediate results obtained 
during the execution of the program. 
This may be required because the storage 
capacity does not suffice to accommodate 
both the program and the data. 

• To store the results obtained by the 
execution of the program (maybe for use 
as input either to the same program at a 
later execution or to another program) . 

A block is the physical unit of informa- 
tion transferred between internal storage 
and the external storage medium of the 
file. 

A record is the unit of information 
which is logically transferred between the 
program and the file by a single PL/I READ, 
WRITE, or REWRITE Statement. A block may 
contain more than one record (blocked reco- 
rds). In blocked record files, the records 
are buffered until a full block has been 
gathered and then physically transmitted to 
the file. In the case of input files, one 
block is read into a buffer, and each READ 
statement transfers (locates) one single 
record to the program. 

A label is a special set of records that 
identifies a magnetic tape file or a direct 
access storage device (DASD) file. Labels 
are processed by the PL/I statements OPEN 
and CLOSE. 

A key is the information required to 
locate a record within a DASD file declared 
with the attribute DIRECT. 



CONSECUTIVE FILES 

The blocks contained in CONSECUTIVE files 
are identified by the sequence in which 
they are stored. This renders it imposs- 
ible to access (or store) the blocks in any 
manner other than sequential. This, in 
turn, implies that the DIRECT attribute is 
not permitted for CONSECUTIVE files. 

A PL/I file declared to be CONSECUTIVE 
may consist of a deck of punched cards, a 
listing on a printer, one or more reels of 
magnetic tape, or some space on one or more 
1316 disk packs used with the 2311 disk 
drive, other storage media for CONSECUTIVE 
files like the paper tape reader, the opt- 
ical character reader, or teleprocessing 
lines (DOS only) may be addressed by using 
subroutines written in Assembler language 
that will process these files. 

For an example showing the creation and 
updating of a sequential disk file, refer 

t o Appendix L. Pro g ramm ing Examples , 

"Creating And Updating a Sequential Disk 
File". 

A magnetic tape file may be contained on 
a single tape reel or on more than one reel 
(multi-reel file) . The logical unit where 
the file is located must be declared in the 
MEDIUM option of the ENVIRONMENT attribute. 
When using a multi-reel file, more than one 
tape drive may be assigned to this logical 
unit by specifying the ALT option in the 
ASSGN statement to overlap processing and 
mounting of tape reels. Only labeled files 
should be used for multi-re6l files. 

A magnetic tape may also contain more 
than one file. To position the file 
correctly an MTC statement may be used to 
space the tape forward over as many tape 
marks as precede the file to be opened. 
(Refer to Multi-File Volumes a nd Backw ards 
Files in the section File Labels.) 



REGIONAL FILES 



File Organization Schemes 

The organization of a file may be consecu- 
tive, regional, or indexed. 

The term file organization is synonymous 
with an algorithm for identifying and 
locating blocks and records on the storage 
medium holding the file. 



The regional file organization is possible 
only for DIRECT DASD files. REGIONAL files 
are processed using the DOS Direct Access 
method. Two different methods are used: 

• REGIONAL (1) where records are addressed 
by their relative position in the file 

• REGIONAL (3) where records are addressed 
(1) by the number of the track on which 
they reside, the track number being 
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relative to the first track of the file 
and (2) by means of a key associated 
with the record. 

For further details refer to the section 
Disk_Organi z at ion , 



B§§iii2ii:2ii^ . REGIONAL files must be de- 
clared with the attributes DIRECT and 
KEYED, which exclude the use of the STREAM, 
PRINT, SEQUENTIAL, and the buffering attri- 
butes. The KEYLENGTH option of the 
ENVIRONMENT attribute is not permitted for 
REGIONALCl) files but must be specified for 
REGIONAL (3) files. REGIONAL files permit 
only fixed unblocked records. The V, U, 
BUFFERS, LEAVE, and NOLABEL options of the 
ENVIRONMENT attribute are not permitted for 
The maximum relative reco- 
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r\JUivjxv-»i.itl 

rd or track nuiriuer is 2""**— ■^. 
statements for REGIONAL files must be supp- 
lied in ascending symbolic- unit order. If 
there are multi-volume files, the symbolic 
units must be assigned in consecutive 
order. 



Note on cqonga t ibil i ty . In OS PL/I, certain 
information contained in the key field or 
data field of REGIONAL files is used to 
flag a record of that file as deleted. 
Therefore, if the user plans to create 
files with DOS PL/I and read and/or update 
them with OS PL/I, he should avoid keys or 
data that would cause OS PL/I to consider 
the record as deleted. For detailed infor- 
mation refer to the pertinent section of 
the 03 PL/I Programmer's Guide, Order 
No. GC28-6594. 



REGIONAL_(l)__Files 

The individual records in a REGIONAL(l) 
file are identified by their position rela- 
tive to the position of the first record in 
the file, which has a relative record numb- 
er of 0, A track is assumed to contain as 
many records as may fit, i.e., if some 
parts of the track are still empty, these 
"holes" are nevertheless counted as real 
records. The number of records per track 
is shown on the Programmer's Reference 
Chart, Form X20-1705. The key used to 
identify individual records and issued with 
the KEY or KEYFROM option of a READ, WRITE, 
or REWRITE statement is not written onto 
the DASD file but specified as a numeric 
field declared as PICTURE '{8)9'. There- 
fore, records to be read from a REGIONAL (1) 
file must not contain keys on the DASD. 
The value contained in the numeric field 
(key) is the relative number of the record 
in the file. 

Crea ting a REG I ONAL (1) Fil e. The extents 
to be used by a PL/I REGIONAL (1) file must 
be Preformatted by the DOS Clear Disk uti- 
lity program. (For details refer to the 
SRL publication IBM System/3 60, Disk a nd 
Tape Operating Systems, _ Utility Progra m 
Specifications, Order No. GC24-3it65-) This 
utility program creates dummy records that 
contain a string filled with user-defined 
characters. The file can then be actually 
created by specifying the OUTPUT attribute. 
Figure 15 shows a sample card deck used for 
Preformatting a REGIONAL(l) file. 



The DLEL and EXTENT statements are 
described in the section File Labels. 



Note 
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Figure 15. Sample Card Decks for Preformatting REGIONAL Files 
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that the dummy file should have an expira- 
tion date that has already been passed 
because, otherwise, the unexpired-file con- 
dition would prevent the PL/I output file 
from being opened. Note further that the 
dummy file is sequential and that its name 
is UOUT, independent of the actual name of 
the file to be used in the PL/I program. 
The UCL statement and the END statement are 
utility control statements and have a fixed 
format, i.e., no additional blanks must be 
inserted. K=0 means that no key is asso- 
ciated with the records. D=100 means that 
the block length is 100. This value may be 
modified to the user's requirements and 
must be identical with the actual block 
length of the PL/I file. The dollar sign 
is the character to which the file is 
cleared. It may be replaced by any other 
character. 



If an attempt is made to write more 
records onto a track than its capacity per- 
mits, the CN KEY condition is raised. 

The KEY and KEYFRQM Options for REGIONAL (3) 
Files. The expression in the KEY or KEY- 
FROM option in READ, WRITE, or REWRITE Sta- 
tements must result in a character string 
whose length is the same as the length spe- 
cified in the KEYLENGTH option of the 
ENVIRONMENT attribute. The last 8 charac- 
ters must be in the form PICTURE •(8)9'. 
The numeric value n represented by the last 
8 characters is used to access the n-th 
track of the file with a key identical to 
the character-string expression, n must be 
less than 2^'*, 



The KEY and KEYFRQM Options for REGIONAL (1) 
Files. The expression in the KEY or KEY- 
FROM option in READ, WRITE, or REWRITE Sta- 
tements must result in a character string 
of the form PICTURE •(8)9'. The value n 
represented by this expression is used to 
access the n-th record of the file relative 
to the beginning of the file, n must be 
less than 2^"*, 

For a programming example refer to 

A2pendix_L^ Programming Examp le s , " Creat- 

ing And Retrieving a REGIONAL(l) File". 

REGigNAL^3)__Fil€S 

Contrary to REGIONAL (1) files, records in 
REGIONAL (3) files are addressed by the 
number of the track on which they are 
located, the track being relative to the 
first track occupied by the file. The 
first track of a REGIONALO) file is coun- 
ted as track 0. Each individual record 
contained in one track is associated with a 
key on the DASD in order to distinguish it 
from other records in that track. The 
length of this key is declared in the KEY- 
LENGTH option of the ENVIRONMENT attribute. 
The key is a concatenation of two strings. 
The first (left) key string is a character 
string of a maxi-mum length of 247 charac- 
ters and contains the information required 
to distinguish the records from the remain- 
ing records on the same track. The second 
(right) key string is a numeric field de- 
clared as PICTURE •(8)9* which contains the 
relative track number. The full key is 
written onto, or read from,, the DASD file. 

Like REGIONAL (1) files, REGIONAL (3) 
files require preformatting by the DOS 
Clear Disk Utility program. In addition to 
its clearing function, the utility program 
resets the record RO (capacity record) to 
reflect that all tracks are empty. The 
file can then be actually created by speci- 
fying the OUTPUT attribute. 



INDEXED FILES 

This file organization is 
DOS PL/I compiler and by 
macro instructions. Both 
used to create, access, a 
with the indexed- sequenti 
tion. For details on the 
instructions refer to the 
System/360 Disk Operating 



supported by the 
the PL/ I DASD 

methods may be 
nd update files 
al file organiza- 
PL/I DASD macro 
publication IBM 
System , PL/I DASD 



Macros, Order No. GC2U-5059, 



Indexed-Sequgntial Organization 

An indexed-sequential file is one whose 
records are organized on the basis of a 
collating sequence determined by control 
fields (referred to as keys) that precede 
each block of data. The key for each block 
of data is from 1 to 255 bytes in length 
and contains the identifier of the last 
logical record in that block. Indexed- 
sequential files are contained in some 
space allocated on direct access volumes as 
prime areas and index areas. 

The indexed-sequential file organization 
gives the programmer great flexibility in 
the operations he can perform on a file. 
Using this scheme of file organization, he 
has the ability to 

• read or write (in a manner similar to 
that for sequential files) logical reco- 
rds whose keys are in ascending collat- 
ing sequence. 

• read or write random logical records. 
If a large portion of the file is being 
processed, reading records in this mann- 
er is somewhat slower than reading 
according to a collating sequence since 
a search for pointers in indexes is 
required for the retrieval of each 
record. 
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add logical records with new keys. The 
system locates the proper position in 
the file for the new record and modifies 
the indexes accordingly. 



Indexes, The ability to read and write 
records from anywhere in an indexed- 
sequential file is provided by indexes that 
are part of the file. There are always two 
types of indexes: a cylinder index for the 
entire file, and a track index for each 
cylinder. An entry in a cylinder or track 
index contains the identification of a spe- 
cific cylinder or track and the highest key 
associated with that cylinder or track. 
The system locates a given record by its 
key after a search of a cylinder index and 
a track index within that cylinder. 



A third type of index, the roas ter_index , 
is optionally available for very large 
files. A master index is generated only if 
the INDEXMQLTIPLE option is specified in 
the declaration of the respective output 
file. The master index contains an entry 



fnr 



-y^ -l-T-ai^lr 



master index is present, the search in the 
cylinder index is limited to a search on 
one track. For usual applications, a mast- 
er index is not recommended if the cylinder 
index consists of less than four tracks. 



The track index always resides on the 
same extent as the prime data area. The 
cylinder and master index may reside on the 
same volume as the prime data area; howev- 
er, they may also reside on a different 
volume of a different DASD type. The 
cylinder index must be immediately adjacent 
to the master index, if any, on the same 
volume. Master and cylinder index must be 
completely contained in one volume. 



Insertion of Records. A new record added 
to an indexed-sequential file is placed 
into a location on a track which is deter- 
mined by the value of its key field. If 
records were inserted in precise physical 
sequence, insertion would necessi«tate 
shifting all records of the file that have 
keys higher than that of the one inserted. 
However, an overflow area is available for 
each cylinder. Thus, a record can be 
inserted into its proper position with only 
those records on the track being shifted in 
which the insertion is made. 



2Y§Ef i25*_^£§§ • ^^ addition to the prime 
area, whose tracks initially receive the 
records of an indexed-sequential file, 
there is an overflow area for records for- 
ced off their original tracks by insertion 
of new records. When a record is to be 



inserted, the records already on the track 
that are to follow the new record are writ- 
ten back onto the track after the new reco- 
rd. The last record on the track is writ- 
ten onto an overflow track. Figure 16 
illustrates this adjustirent for addition of 
records to an indexed-sequential file whose 
keys are in a numerical ascending sequence. 



initiai Format of File 
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Format of File after iniertion of Records 17-22 
and Record 9 
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Prime Track 1 
Pri-,« Tfock 2 



Overflow Track 1 11 mm 10 




Figure 16. Addition of Records to a 1- 
Cylinder, 3-Track Indexed- 
Sequential File 



When this file is created,, its records 
are placed on the prime tracks in the 
storage area allocated to the file- If a 
record, e.g., record 7, is to be inserted 
into the file, the indexes indicate that 
record 7 belongs on primary track 1^ Reco- 
rd 7 is then written immediately following 
record 5, and records 8 and 10 are retained 
on this track. Since record 11 no longer 
fits, it is written onto an overflow track 
and the proper track index is adjusted to 
show that the highest key on prime track 1 
is 10 and that an overflow record exists. 
When records 17 to 22 are added to the end 
of the file, prime track 2 receives records 
17 to 21 but record 22 does not fit and is 
written following record 11 on the overflow 
track. When record 9 is inserted* record 
10 is shifted to the overflow track after 
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record 22. Note that records 10 and 11 on 
the overflow track are chained together to 
show their logical sequence and to indicate 
that they belong to the same prime track. 



specified to indicate embedding, the key is 
inserted automatically into the field dur- 
ing creation of the file or during addition 
of records to the file. 



Independent _Over flow Area. An independent 
overflow area can be specified by an EXTENT 
statement (before the program is executed) 
to specify the area extent. If one or more 
of the (cylinder) overflow area(s) become 
full, additional overflow records are writ- 
ten on the independent overflow area. This 
area may be on the same volume as the data 
records or on another volume, but must be 
contained on one single volume. The number 
of overflow tracks reserved on each cylind- 
er of the prime data area is determined by 
the OFLTRACKS option of the ENVIRONMENT 
attribute. 



When using the PL/I DASD macro instruc- 
tions, two tracks per cylinder are reserved 
as overflow area. The number of extents 
per file with PL/ I DASD macro instructions 
is restricted to ten. Note that the 
cylinder index constitutes a separate 
extent. 



The location of index areas, overflow 
areas, and the prime data areas on DASD 
devices are specified by means of DLBL and 
EXTENT statements. (Refer to the section 
File Labels.) 



Record Format and Keys. With indexed 
files, "^all records must be of fixed length 
(blocked or unblocked). Since only one key 
is permitted per block on DASD devices, the 
access method for blocked records requires 
that the key be embedded in the data field 
of the record. The location of the key 
within the record is specified by the KEY- 
LOC option of the ENVIRONMENT attribute. 
The key must be embedded in the data field 
if records are blocked; it may be embedded 
if the records are unblocked. If KEYLOC is 



When the PL/I DASD macros are used, a 
record key is located within each record, 
and one extra key is associated with each 
block. This key is identical with the 
highest (or only) record key in the block. 



When processing INDEXED tiles, the KEY 
condition is raised in a number of cases. 
If the programmer wants to identify a spe- 
cific situation at execution time, take 
action, and continue processing, it is sug- 
gested to include the following coding in 
the program: 



DCL ERRBYTE BIT (8) EXTERNAL; 

CALL ERROUT (ERROUT is an Assembler 
routine which returns in 
ERRBYTE the contents of the 
error byte) 



IF :ERRBYTE = '00 000100 'B THEN ... 

(duplicate record, for 
example) 



The contents of the error byte for 
indexed-sequential output files and the 
corresponding ON-conditions raised are as 
shown in Figure 17. 



The contents of the error byte for all 
other indexed files and the corresponding 
ON-conditions raised are as shown in Figure 
18. 



The Assembler routine ERROUT is shown in 
Figure 19. (The address of the error byte 
is in the 10th word of the DTF-appendage. ) 
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Bin 


CoHise 


Explanation 


ON condition 
raised 


Followed by 
PI/I Message 





DASD «rror 


Any uncorrectable DASD error has occurred (except wrong length record). 


OC 


- 


1 


Wrong length record 


A wrong length record has been detected during on I/O operation. 


OE 


- 


2 


Prime dota area full 


The next to the lost track of the prime data area has been filled during the load 
or extension of the data file. The problem progrcimmer shoc'ld issue the ENDFL 
macro, then do a load extend on the file with new extents given. 


nn 


82 


3 


Cylinder Index erse fyl! 


The Cylinder Index area is not large enough to contuin all the enwies needed to 
index each cylinder specified for the prime data area. This condition con occur 
during the execution of the SETFL. The user must extend the upper limit of the 
cylinder index by using a new extent card. 


- 


71 


4 


Master index full 


The Master Index area is not large enough to contain all entries needed to index 
each track of the Cylinder Index. This condition can occur during SETFL. The 
user must extend the upper limit, if he is creating the file, by using an extent 
card. Or, he must reorganize the data file and assign a larger area. 


- 


71 


5 


Oupiicate record 


The record being looded is a duplicate of the previous record. 


OD 


83 


6 


Sequertce check 


The record being loaded is not in the sequential order required for looding. 


OD 


84 


7 


Prime data area overflow 


There is not enough space in the prime data area to write an EOF record. This 
condition con occur during the execution of the ENDFL macro. 


- 


- 



Figure 17, Contents of Error Byte For Indexed-Sequential Output Fil 



es 



Bit 


Cause 


Explanation 


ON-conditon 
raited 


Followed by 
Pl/I AAessage 





DASD error 


Any uncorrectable DASD error has occurred (except wrong length record). 


OC 


70* 


1 


Wrong length record 


A wrong length record has been detected during on I/O operation. 


OE 


- 


2 


End of file 


The EOF condition has been encountered during execution of the sequential 
retrieval function. 


OA 


- 


3 


No record found 


The record to be retrieved ho$ not been found in the dato file. This applies to 
Rondom (RANSEQ) and to SETL in SEQNTL (RANSEQ) when KEY is specified, 
or after GKEY. 


OA**or 
OD 


80 


4 


Illegal ID specified 


The ID specified to the SETL in SEQNTL (RANSEQ) is outside the prime data 
file limits. 


- 


- 


5 


Duplicate record 


The record to be added to the file has a duplicate record key of another record 
in the file. 


OD 


83 


6 


Overflow area full 


An overflow area in o cylinder if full, and no independent overflow area has 
been specified, or or* independent cvcflcw area is full, and the addirioo cannot 
be mode. The user should assign on independent overflow area or extend the 
limit. 


OD 


81 


7 


Overflow 


The record being processed in one of the retrieval functions (RANDOA^/SEQNTL) 
is on overflow record. 


- 


- 


* For indexed-sequential with READ KEY 

** DA is raised if the key is too high, otherwise OD is raised. 



Figure 18. Contents of Error Byte For All Other Indexed Files 



ERROR 


START 







EXTRN 


ERRBYTE 




USING 


*,9 




STM 


14,12,12(13) 




LR 


9.15 




LA 


10, SAVE A 




ST 


13,4(10) 




LR 


13,10 




MVC 


INDIC+2(l),INDIC+3 




L 


1,FILE 




L 


1,36(1) 




L 


4 , AERRBYTE 




USING 


ERRBYTE, 4 




MVC 


ERRBYTE (1) ,0(1) 




L 


13,4(13) 




LM 


14,12,12(13) 




BR 


14 




DS 


OF 


SAVEA 


DC 


X'03' 




DC 


AL3 (INDIC) 




DC 


F'O' 


INDIC 


DC 


3X'0' 




DC 


X'F8' 


FILE 


DC 


V (filename) 


AERRBYTE 


DC 
END 


A (ERRBYTE) 


Figure 19 


Assembler Routine ERROU 



NO RECORD condition will be raised for 
retrieving or updating files. The IOCS 
module gets the record length during OPEN 
time from the format-2 file label as it was 
written at creation time. No checking is 
made between this entry and the entry in 
the DTF table- 

For blocked records, the RECORD condi- 
tion will be raised when the first record 
of a block with one or more wrong -length 
records is read. With each execution of a 
READ statement the RECORD condition is 
raised until the last record of the block 
has been read. 



Note on Compatibility. In OS PL/I, certain 
information contained in the key field cr 
data field of INDEXED files is used to flag 
a record of that file as deleted. There- 
fore, if the user plans to create files 
with DOS PL/ I and read and/or update them 
with OS PL/I, he should avoid keys or data 
that would cause OS PL/ I to consider the 
record as deleted. For detailed informa- 
tion refer to the pertinent section of the 
OS PL/I Programmer's Guide, Form C28-6594, 



Disk Organization 

As an example of a DASD organization, this 
section describes the 1316 disk pack used 
with the 2311 Disk Storage Drive. The 2316 
disk pack used with the 2314 or 2319 Direct 
Access Storage Facility is organized very 
similarly. However, the 2316 disk pack 
consists of 11 disks with 20 surfaces on 
which data is recorded vjith double density. 
For further details (also on the 2321 Data 
Cell Drive) refer to the publications IBM 
System/ 360 Component Descriptions , Or der 
No. GA26-3599 (for the 2314) and IBM 
System/360 Co mponent Descriptions , Or der 
No. GA26-5988 (for the 2311 and 2321). 

The 2311 DASD uses 1316 disk packs as 
recording medium. One disk pack consists 
of 6 disks. The top surface of the upper 
disk and the bottom surface of the lowest 
disk are not used, which leaves 10 surfaces 
for recording. Each disk surface contains 
203 concentric tracks. Track 1, 2, 3, 
etc., on each surface is physically located 
below or above track 1, 2, 3, etc., of the 
other surfaces. Therefore, the correspond- 
ing tracks are referred to as 203 concentr- 
ic cylinders. 200 cylinders are used for 
actual recording; the remaining 3 are 
reserved. 



The IOCS modules used by the PL/I (D) 
compiler are not reentrant. The PL/I 
library routine IJKTXCF deblocks such a 
wrong-length record. No other file using 
the same IOCS module may raise the RECORD 
condition before the wrong- length record 
has; been deblocked to the end. 



The KEY, KEYFROM, and KEYTO Options for 
INDJIXED Files. The expression or variable 
in the KEY, KEYFROM, or KEYTO option of 
READ, WRITE, or REWRITE Statements must 
result in or be a character string of the 
same length as the length specified in the 
KEYLENGTH option Of the ENVIRONMENT 
attribute. 

Note: In indexed-sequential files, retri- 
eval, updating, and adding of records can 
be performed either sequentially or at ran- 
dom. However, indexed-sequential files can 
be created only sequentially. 



The 2311 is provided with one access arm 
equipped with 10 read/write heads. The 
heads aire mounted vertically so that data 
contained in one cylinder can be accessed 
without any mechanical movement. This, 
however ,~^ renders it necessary to internally 
switch from surface to surface within a 
cylinder in case one track (of a consecu- 
tive file) is completely filled. When a 
cylinder is filled, reading or writing is 
resumed on the first track of the next 
cylinder. This technique minimizes the 
access- at m movement time. 

Thus, a disk pack is thought of as con- 
sisting of 200 cylinders, each cylinder 
consisting of 10 tracks. A consecutive 
part of cylinders (or tracks) set aside for 
usage by a specific file is referred to as 
an extent. An extent is defined by an 
EXTENT statement (refer to the section File 
Labels) . In case two or more files are to 
be accessed alternating ly, each individual 
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Record (Track 
Descriptor) RO 



Record 1 
Rl 



Record 2 
R2 




Defines the location of the track in 

terms of the physical parameters of 
the files. 

Index Marker 



Indicates the physical beginning of each track. 



Address Morker 

Indicates the beginning of a new record. The 
record RO does not have an address marker. 



Figure 20. Contents of a Track 



file may be assigned a part of consecutive 
tracks per cylinder instead of full cylin- 
ders. For instance, tracks to 4 of 
cylinders 10 to 99 may be assigned to 
FILEA, while tracks 5 to 9 of the same set 
of cylinders may be assigned to FILEB. The 
latter technique is referred to as split- 
c^linder technique. '~ 

The information contained on a track is 
recorded in physical records (see Figure 
20). Each physical record consists of 2 or 
3 fields- 

The first field is a count field (C) 
identifying the record.. The programmer is 
not concerned with this field. The second 
field is the key field (K) . It has the 
length given in the KEYLENGTH option of the 
ENVIRONMENT attribute or in the KEYLEN 
operand of a PL/I DASD macro instruction 
and contains the key given in the KEY or 
KEYFROM option. CONSECUTIVE and REGIONAL ( 
1) files have no key field. The last field 
is the data field (D) and contains the 
block to be read or written. "Hie first 
record (Track Descriptor) of each track 
(RO) is not part of the information trans- 
ferred by a FL/I program but contains some 
statistical information. The home address 
(HA) is of no interest to the PL/I 
programmer. 



Record Types 

These are five record types that can be 
handled by PL/I programs: 

fixed unblocked 
fixed blocked 
variable unblocked 



variable blocked 
undefined 



Fixed Unblocked Records 



All records are of the same length. Each 
block contains exactly one record. The 
ENVIRONMENT option used is F(iti). 



Fxx ea Bioo cea Kecords 

All records are of the same length. Each 
block contains a fixed number of records. 
(Only the last block of a file may contain 
less records,) The ENVIRONMENT option used 
is F(m,n). 

Variable Block ed R ecords 

The records are of variable length, each 
block containing a variable number of reco- 
rds. However, a maximurr block length is 
specified. To enable the input/output con- 
trol routines to determine the lengths of 
blocks and records, the blocks contain 
extra fields that are not part of the actu- 
al record. The first 4 bytes of each block 
contain a block control field. Each record 
in the block is also preceded by a 4-byte 
record control field. The ENVIRONMENT 
option used is V(ro), where m is the maximum 
block size, m must include the number of 
bytes required by both the records and the 
control fields. 

The D Compiler automatically supports 
variable- length blocked records if V(m) is 
specified,, i.e., it always accommodates as 
many records in a block as will fit. 
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If at the end of a track there is not 
enough space for the whole block, the I/O 
routines write part of the block (but com- 
plete user-defined records) at the end of 
the track and shifts the remaining records 
onto the next track. Boundary problems may 
occur, however, if the rules for using the 
LOCATE statement with the SET option are 
not followed. 



Variable Unblocked _Records 

This is a real subset of variable blocked. 
With variable unblocked records, the value 
of m in V(m) is 8 higher than the largest 
possible record in the file. Variable 
blocked and variable unblocked records may 
be intermixed. 

The records are of variable length. Each 
block contains one record. No control 
fields are used. The ENVIRONMENT option 
used is U(tn) . 

B§§t£i9ti2ll§ 

For the restrictions regarding the block 
length refer to Appendix J under Blocks! ze 
Options . 

A block has the meaning that the physic- 
al storage medium is advanced one block 
after the corresponding operation has been 
performed. In the case of punched cards, 
for instance, this implies that one card is 
read or punched. This, in turn, implies 
that the remainder of the card is ignored, 
and the next block starts with transmission 
of column 1 of the next card in case a 
block length of less than 80 bytes is spe- 
cified for a card file. 



Input/Output Processing 

Access Methods 



Note; Indexed-sequential files may be read 
or updated either sequentially or direct. 

Note: If two or more files are simul- 
taneously open on the same physical non- 
DASD device or DASD extent, the order of 
access to the files is unpredictable. Read 
and punch feed of a 254 Card Read- Punch 
count as two different devices. For 
example, a read and a punch file cannot be 
open at the same time using the same 1442 
or 2520 Card Read-Punch. As another 
example, if there is a record file assigned 
to a printer and the standard system - 
STREAM - file uses the same printer, both 
files have their own buffers and print 
independently of each other, i,e., the 
printed lines will not necessarily appear 
in the same sequence as the WRITE and PUT 
statements are executed. 

Buffering 

A buffer is a part of storage used to 
accommodate data to be read or written. 
Buffers are used to allow transmission of 
data asynchronously to the program flow. 

Files with the UNBUFFERED attribute 
allow no overlapping of input/output opera- 
tions. In files declared with the BUFFERED 
attribute, execution of I/O operations is 
overlapped if the option BUFFERS (2) is spe- 
cified in the ENVIRONMENT attribute. For 
files declared with the BUFFERED attribute, 
the buffers can be made available for use 
as work areas by using the READ statement 
with the SET option or the LOCATE state- 
ment, i.e. J the based record variables are 
located directly in the buffers. 

Tape files with the UNBUFFERED attribute 
must also have the NO LABEL attribute. 
Therefore, no multi-volume files or 
alternate-tape specifications are 
permitted. 

If OUTPUT is specified in addition to 
UNBUFFERED and NOLABEL, tape labels are not 
checked and not overwritten. 



Since records in files declared with the 
CONSECUTIVE option are identified merely by 
the sequence in which they are created, the 
only possibility to read, write, or update 
records in such files is to sequentially 
process the file from its starting point. 
This procedure is referred to as the 
sequential access method, and files so 
accessed have the attribute SEQUENTIAL. 

In other files, the records are identi- 
fied by keys. In this case, each individu- 
al record can be accessed by use of the key 
regardless of the physical location of the 
record. This procedure is referred to as 
the direct_access method, and a file so 
accessed has the attribute DIRECT. 



Disk input and update files with the 
UNBUFFERED attribute are opened with the 
output OPEN routine. Therefore, the 
expiration date for such files must be 
lower than the current date. 

Although buffering attributes are not 
permitted for DIRECT files, one buffer is 
assigned to REGIONAL and INDEXED DIRECT 
files. The minimum length of the buffer is 
the record length. The maximum length of 
the buffer is the record length + keylength 
+ 8 for REGIONAL files and INDEXED DIRECT 
INPUT files. For INDEXED DIRECT UPDATE 
files, the maximum length of the buffer is 
the block length + keylength +8+10 (for 
the sequence link field) . 
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File Labels 



A tape reel or disk pack may contain infor- 
mation that is required for a certain 
period of time. Therefore, each file (tape 
reel or disk extent) must be checked for 
its expiration date. In addition, a check 
must be performed to determine if the prop- 
er volume has been mounted for processing. 
These checks are performed by reading and 
comparing special records that are con- 
tained in the respective volume. These 
special records, which are referred to as 
labels, are processed whenever an OPEN or 
CLOSE statement is executed for a particu- 
lar file. 

The label information is furnished by 
means of special Job Control statements, 
which are described later in this section. 
There are two types of labels: volume 
labels and file labels. 

7Glume_label3 are used to identify the 
volume (tape reel or disk pack) , During 
execution of the OPEN routine, the volume 
serial number is compared against the 
information supplied to the Supervisor, 
Volume labels can be created by means of 
IBM-supplied utility programs. 

File labels describe the file to be pro- 
cessed'~by the program and indicate whether 
or not the file must be retained for a cer- 
tain period of time. When an OPEN state- 
ment is encountered, the information con- 
tained in the file labels of input and upd- 
ate files is compared against the informa- 
tion supplied to the Supervisor. If a mis- 
match is found, a message to the operator 
is printed. When an OPEN statement is 
encountered for an output file, the expira- 
tion date in the file label is checked 
against the date stored in the communica- 
tion region of the Supervisor. If the 
expiration date has been neither reached 
nor passed, a message to the operator is 
printed and the execution of the program is 
interrupted. In case the expiration date 
has been reached or passed, a new file 
label is created from the information supp- 
lied through the control cards. The old 
file label is overwritten by the new file 
label. 

Labeled tape files have two types of 
labels: header labels and trailer labels. 
The header label precedes each file and 
defines it. The trailer label is written 
at the end of the file. It furnishes the 
information required to determine whether 
the end of the file has been reached or 
whether the file is continued on another 
volume. Tape files may also be unlabeled. 



This condition is specified by the option 
NOLABEL in the ENVIRONMENT attribute. 

Disk files must be labeled. Disk file 
labels do not precede or follow the indivi- 
dual file. They are contained in a special 
region referred to as the VTOC (Volume 
Table Of Contents). Disk labels are 
updated either during execution of the 
CLOSE routine or when an end-of-extent is 
reached. Switching from volume to volume 
for multi-volume files is effected automat- 
ically without any programming effort. 

Note: Punched-card and print files must 
not be labeled. 

For detailed information and restric- 
tions on label processing see the SRL pub- 
lications describing the DOS/TOS data mana- 
gement concepts, the DOS/TOS Supervisor and 
I/O macro instructions, and the DOS system 
control and service programs. 



Processing of File Labels by PL/I 

PL/I does not provide for label processing 
of UNBUFFERED files. However, file labels 
are checked for expiration (also if INPUT 
is specified) and cleared. The volume 
label is maintained. 

No provision has been made for label 
processing of the standard PL/I files SYSIN 
and SYSPRINT. 

As far as label processing is concerned, 
UPDATE and INPUT files are handled in the 
same manner. 



Job-Control Statements 

A set of Job Control statements is required 
for each labeled file. This set of state- 
ments must be in a specific sequence and 
immediately precede the // EXEC statement 
for the job step in which the file is 
processed. 

Each set of label information submitted 
within a job or job step is written in the 
appropriate temporary label information 
area. This information is not carried from 
job to job. Unless overwritten by a suc- 
ceeding job step, any label information 
submitted at the beginning of a job can be 
used by a subsequent job step. For 
example, if a job consists of three job 



steps, label information submitted at the 
beginning of the first job step can be used 
by the second and third job steps of the 
job. However, label information submitted 
at the beginning of the second job step 
would destroy the label information written 
at the beginning of the first job step. 

Note: DLBL and EXTENT Job Control state- 
ments for SYSIPT, SYSLST, or SYSPCH must 
precede the corresponding permanent ASSGN 
commands . 

The sequence of Job Control statements 
for disk labels is as follows: 

// DLBL 

// EXTENT (one or more) 

The Job Control statement for tape 
labels is as follows : 

// TLBL 



tion period may be specified for output 
files. If this operand is omitted, a 7-day 
retention period is assumed for output 
files. For input files, no checking is 
performed if this operand is omitted or if 
a retention period is specified. 



codes is a 2- or 3-character field indicat- 
ing the type of file label as follows: 

SD for Sequential Disk, 

DA for REGIONAL files, 

ISC for Indexed Sequential using Load Cre- 
ate, or 

ISE for Indexed Sequential using Load 
Extension, Add, or Retrieve. 

SD is assumed if this parameter is 
omitted. 



The syntax rules are the same as those 
for the other Job Control statements. 
Trailing commas not followed by an operand 
may be suppressed. 

Note: The former disk and tape label Job 
Control statements DLAB, VOL, XTENT, and 
TPLAB may still be used. However, the old 
and new disk label statements must not be 
intermixed, i.e., XTENT is associated with 
DLAB and VOL, and EXTENT is associated with 
DLBL, 



The^DLBL_Statement 

The DLBL statement furnishes the disk file 
label information. The format of this sta- 
tement is as follows: 

// DLBL filename, ['file-ID* 3 , [date] , [codes] 

The meaning and format of the operands is 
described below: 



For output files, the current date is 
used as the creation date. 



The EXTENT Statement 

The EXTENT statement defines an extent of a 
DASD file. One or more EXTENT statements 
must follow each DLBL statement. The 
EXTENT statement has the format 

// EXTENT [SYSxxx],[ssssss]„ [t],, [nnn], 
[rrrrr], [mmmmm], [dd] 

The meaning and format of the operands is 
described below. 

SYSxxx (symbolic unit) is a 6-character 
field that indicates the symbolic unit of 
the volume to which this extent applies. 
If this operand is omitted, the symbolic 
unit of the preceding EXTENT statement is 
used. 



filename is identical to the name of the 
PL/ I file. 

_[_file-ID^ is the name of the file that is 
recorded on the disk drive as an identifi- 
cation of the file. It may comprise from 1 
to 44 bytes of alphameric data. If less 
than 44 characters are used,, the field is 
left- justified and padded on the right with 
blanks. If this field is omitted, the file 
name is used as file-ID. 

date is a field of one to six numeric 
characters. Two formats are possible. The 
first format is yy/ddd, which indicates the 
expiration date of the file for output or 
the creation date for input. (The day of 
the year may have from one to three charac- 
ters.) Optionally, a 1- to 4-digit reten- 



For multi-volume REGIONAL files the sym- 
bolic unit numbers in the corresponding 
EXTENT statements must be in direct ascend- 
ing sequence (e.g., SYS006, SYS007, 
SYS008). 

ssssss (serial number) is a field of one to 
six characters that indicates the volume 
serial number of the volume to which this 
extent applies. If less than six charac- 
ters are used, the field is right-justified 
and padded to the left with zeros. If this 
operand is omitted, the volume serial numb- 
er of the preceding EXTENT statement is 
used. If no volume serial numbed was pro- 
vided in that statement, the serial number 
will not be checked, (Files may be des- 
troyed in this case due to mounting of the 
wrong volume.) 
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t (type) is a l-digit field indicating the 
type of extent as follows: 

1 - data area (no split cylinder) 

2 - independent overflow area (for indexed 

sequential file) 
4 - index area (for indexed sequential 

file) 
8 - data area (split cylinder) 

Type 1 is assumed if this operand is 
omitted. 

nnn (sequence number) is a field of one to 
three characters that contains a decimal 
number from to 255. The decimal number 
indicates the sequence number of the extent 
within a multi-extent file. For indexed 
files, the sequence number is always 
associated with the master index. Thus, if 
a master index is specified, the sequence 
number for indexed files starts with 0; 
otherwise, i.e., if no master index is 
used, the first extent of an indexed file 
has the sequence number 1, The extent 
sequence number for all other types of 
files begins with 0, If this operand is 
omitted for the first extent of ISFMS 
files, the extent is not accepted. This 
operand is not required for SD and DA 
files. 

rrrrr (relative track number) is a field of 
one to five characters that indicates the 
sequential number of the track (relative to 
zero) where the data extent is to begin. 
For instance, track of cylinder 150 on a 
2311 has the relative track number 1500. 
If this operand is omitted on an ISFMS 
file, the extent is not accepted. The 
operand is not required for SD or DA input 
files (the extents from the file labels are 
used in this case) . 

mmitimm (number of tracks) is a field of one 
to five characters that indicates the numb- 
er of tracks to be alotted to the file. 
The operand may be omitted for SD or DA 
input files. For split cylinders, the 
number of tracks must be an even multiple 
of the number of tracks per cylinder speci- 
fied for the file. 

dd (split cylinder track) is a field of one 
or two digits that indicates the upper 
track number for the split cylinder in SD 
files. 

Note: For INDEXED and REGIONAL files the 
LBLTYP card must also be present. 



// TLBL filename, ['file- ID'], [date] , 
[file-serial- number] , 
[ volume-sequence-nurrber ] , 
[file-sequence-number] , 
[generation-number] , 
[vers ion- number] 



xhe meaning and format ot the operands 
is described below. 



filename is a field of one to six charac- 
ters identical to the name of the PL/ I 
file. 



2.file-lD'_ is a field of one to 17 charac- 
ters, contained within apostrophes, that 
indicates the name associated with the file 
on the volume. This operand may contain 
embedded blanks. If this operand is 
omitted for output files, filename is used 
instead. If this operand is omitted for 
input files, no labels are checked. 



date is a field of one to six numeric 
characters. Two formats are possible. The 
first format is yy/ddd, which indicates the 
expiration date of the file or output or 
the creation date for input. (The day of 
the year may have from one to three charac- 
ters.) Optionally, a 1- to U-digit reten- 
tion period may be specified for output 
files. If this operand is omitted, a 0-day 
retention period is assumed for output 
files. For input files, no checking is 
performed if this operand is omitted or if 
a retention period is specified. 



file-serial-number is a field of one to six 
characters that indicates the volume serial 
number of the first (or only) reel of the 
file. If less than six characters are spe- 
cified, the field is right- justified and 
padded with zeros. If this operand is 
omitted for output files, the volume serial 
number of the first (or only) reel of the 
file is used. If this operand is omitted 
on input, no checking is performed. 



Y2ly50§I.^e9uence2number is a field of one to 
four digits. The sequence numbers of the 
volumes of a multi-volume file must be in 
ascending order. If this operand is 
omitted for output files, BCD 0001 is 
assumed. No checking is performed if this 
operand is omitted for input files. 



Ihe_TLBL_Statement 

The TLBL statement contains file label 
information for tape label checking and 
writing. Its format is as follows: 



f ile-seguence-number is a field of one to 
four digits. The sequence numbers of the 
files of a multi-file volume must be in 
ascending order. If this operand is 
omitted for output files, BCD 0001 is 
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assumed. No checking is performed if this 
operand is omitted for input files. 



generation-number is f field of one to four 
characters that modifies the file-ID. If 
this operand is omitted for output files, 
BCD 0001 is assumed. No checking is per- 
formed if this operand is omitted for input 
files. 

version-nu mber is a field of one or two 
characters that modifies the generation 
number. If this operand is omitted for 
output files, BCD 01 is assumed. No check- 
ing is performed if this operand is omitted 
for input files. 

Notes : 

1. For output files, the current date is 
used as the creation date. 

2. As far as label processing is con- 
cerned, UPDATE files are handled the 
same as INPUT files. 



The following three statements in Figure 
21 show an example the creation of an inde- 
xed sequential file by usage of the PL/I 
DASD macro LODIS, In addition to the pre- 
vious example, the expiration date of the 
file (March 1, 1969) and the code ISC is 
specified in the DLBL statements. There are 
two EXTENT statements. The first one spe- 
cifies the extent of the cylinder index, 
which is extent 1. It starts at track 
number 1000 (i.e.,, cylinder 100, track 0) 
on logical unit SYS004 and consists of 10 
tracks. The data area, which is the second 
extent, resides on a different logical 
unit: SYS005. The extent number need not 
be specified in this case, but the delimit- 
ing comma must be written. 

The last statement in Figure 21 gives an 
example of a TLBL statement. The file is 
assumed to be an input file. It is no 
multi-file volume and a version number is 
not used. Since it is an input file, no 
date entry has been specified. 



Examples for Label Statements 

The first two statements in Figure 21 show 
an example of DLBL and EXTENT statements 
used for a sequential 2311 disk input file. 
The statements identify the file declared 
as MASTIN in a PL/I program. Its external 
identification (stored in the VTOC) is 
MASTER- INVENTORY- FILE. No further entries 
in the DLBL statement are required for an 
input file. 



The logical unit used for the file is 
SYS005 and the volume identification of the 
1316 disk pack to be mounted on 3YS005 is 
VOL172. No further EXTENT statement 
operands are required. 



Multi-File Volumes And Backwards Files 

The handling of multi-file volumes on the 
2311 requires no special preparation since 
all file labels are available when the file 
is opened. When using tape files, the tape 
must be positioned so that the lalsel can be 
checked during execution of the OPEN rou- 
tine. Positioning is not required for the 
first, file on the tape because it is auto- 
matically positioned unless the LEAVE 
option has been specified. For correctly 
positioning the tape for the second, third, 
..., nth file, the LEAVE option must be 
specified in the ENVIRONMENT attribute. 
This prevents the OPEN routine from rewind- 
ing the tape reel. A labeled tape file has 
the format shown in Figure 22. 
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Figure 21. Examples for Disk and Tape Label Statements 
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To position a tape reel that contains 
labeled files at the nth file, the tape 
reel must first be rewound and then spaced 
forward in such a manner that the first 
information read is the header label of the 
nth file. The Job Control statement used 
to control tape drive operations has the 
following form: 

// MTC code,SYSxxx[,nn] 

The operand code is one of che following 
function codes: 

BSF backspace file 

BSR backspace record 

ERG erase gap 

FSF forward space file 

FSR forward space record 

REW rewind 

RUN rewind and unload 

WTM write tape mark 

Forward-space-file and backspace-file 
cause the read head to be positioned at the 
record following the next tape mark that is 
encountered. 

The operand gjfSxxx is the logical device 
address of the tape drive on which the per- 
tinent tape reel is mounted. 

The operand nn is a decimal number from 
01 through 99 that specifies the number of 
times the specified function is to be per- 
formed. If this field and the comma pre- 
ceding it are omitted, nn is assumed to be 
01. 

The following example shows the MTC sta- 

Leraeats required to position the tape reel 

on SYS006 at the header label of the third 
data file. 

// MTC REW,SYS006 
// MTC FSF,SYS006,03 

In unlabeled tape volumes, the end of 
each file is indicated by a tape mark. A 
tape mark may or may not precede the first 
file. Unlabeled tape files written by PL/I 
programs have a tape mark preceding the 
first file unless NOTAPEMK is specified in 
the ENVIRONMENT attribute. 



If a magnetic tape file has the BACK- 
WARDS attribute, the read head must be 
positioned behind the trailer label of this 
file before the file is opened. In case a 
file has been written and closed just 
before it is re-opened to be read back- 
wards, it is positioned correctly if the 
LEAVE option was specified for the written 
file. Unlabeled BACKWARDS files must start 
with a tape mark. 

If an input file of a multi-file volume 
declared with the LEAVE option has been 
closed and the next file of this volume is 
to be opened (or the same file is to be 
opened in the reserve direction), the mag- 
netic tape is positioned correctly only if 
the ENDFILE condition was raised prior to 
the closing of the file. In the case of 
STREAM input, additional (dummy) GET state- 
ments must be issued to synchronize the 
input stream with the ENDFILE condition. 
To prevent raising of the CONVERSION condi- 
tion, the variables read by these dummy GET 
stateraents should be of the character type. 



Link-Editing And Labeled Files 

Before a program that uses and/or processes 
labeled files can be processed by the Lin- 
kage Editor, the Linkage Editor must be 
instructed to reserve a label area. This 
area must precede the area occupied by the 
program, except in the case of CONSECUTIVE 
disk files where no such area is required. 
To reserve the label area,, a special Job 
Control statement must precede the state- 
ment // EXEC LNKEDT. The type of statement 
used depends on whether the program runs 
under control of the Disk Operating System 
or of the Tape Operating System. 

JQ^^^QgS^^QJ: S"*^^t^"?g?^^§ t^f. P QS 

The format of the Job Control statement for 
processing disk files with the REGIONAL or 
INDEXED option is as follows: 

// LBLTYP NSD(nn) 

The operand nn is the largest number of 
extents to be used by any single file. 
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Note that this number must be enclosed in 
parentheses. 

Note that nn must specify the number of 
EXTENT cards and not the EXTENTNUMBER in 
the ENVIRONMENT attribute. 

The format of this statement for the 
processing of labeled tape files is as 
follows: 

// LBLTYP TAPE 



Note: This statement is not required for 
processing of labeled tape files if REGION- 
AL files are used at the same time. 



JQfa-QQ'^i^^Ql . Statements __f or TOS 

The format of the Job Control statement for 
the processing of labeled tape files is as 
follows: 

// LBLTYP TAPE(nn) 

The operand nn is the number of labeled 
tape files to be processed. 

Figure 23 shows a source deck including 
Job Control statements for processing one 
REGIONAL file with two extents, and two 
tape files. 



// JOB INVENTRY 

// OPTION LINK, LIST, ERRS,60C 

PHASE UPDATE,* 
// EXEC piyi 

INVENTRY: PROCEDURE OPTIONS (MAIN); 

DECLARE MASTER FILE UPDATE RECORD ENVIRONMENT 
(REGIONAL(3). ;..)...., 

BACKUP FILE OUTPUT ENVIRONMENT (MEDIUM 
(SYS007, 2400).... ),..., 
EXEPT FILE OUTPUT ENVIRONMENT (MEDIUM 
(SYS008, 2400).... )...., 



// 
// 
// 
// 
// 
// 
// 
// 

/* 
/& 



END; 

ENTRY 

LBLTYP NSD(02) 

EXEC LNKEDT 

DLBL MASTER, 'MASTER INVENTORY FILE',, DA 

EXTENT SYS005,1427 

EXTENT SYS006,1431 

TLBL BACKUP, 'BACKUP INVENTORY', 100, 2711,,, 10, 8 

TLBL EXEPT, 'EXCEPTION INVENTRY', 30,2614,,, 10,0 

EXEC 

data 



Figure 23. Sample Source Deck with Control 
Statements 



CATALOGING OF LABEL INFORMATION 

For DOS, the DLBL, EXTENT, and TLBL state- 
ments for sequential files may be cataloged 
as standard files so that the programmer is 
relieved from issuing the control cards 
with each execution of the program. For 
details refer to the SRL publication 
describing the DOS system control and sys- 
tem service programs. 



Program-Label Communication 

Figure 24 shows the communication between a 
PL/I source program, the object program. 
Job Control statements, and a 2311 disk 
unit with a 1316 disk pack. 

The LIOCS (Logical Input/Output Control 
System) table produced by the PL/ I compiler 
somewhere contains the file name as a 
character string. The communication 
between this table and the actual file 
extent (s) is established by storing the 
extent information in the table during 
execution of the OPEN statement. 

The set of label statements (DLBL, 
EXTENT) to be used for opening the file is 
the one whose DLBL statement contains the 
same file name as stored in the character 
string of the LIOCS table. The logical 
device address is taken from the EXTENT 
card. The physical unit — in this case a 
2311 disk drive — is then determined from 
the standard assignment or from the tem- 
porary assignmients, respectively. The 
serial number field of the EXTENT statement 
is compared against the volume label of the 
1316 disk pack to determine whether the 
right pack has been mounted. 

The remaining action depends on the file 
type. For INPUT or UPDATE files, the VTOC 
on the disk pack is searched for a label 
matching the file-ID issued in the DLBL 
statement (MY DEAR FILE in Figure 2H.) 
When a matching label is found, the remain- 
ing file information is checked against the 
label information in the VTOC, and the 
extent information is passed to the LIOCS 
table to allow proper addressing of the 
blocks to be transferred. 

In case of OUTPUT files, all existing 
labels in the VTOC are checked against 
overlap with the file to be created. The 
file is opened only if there is no overlap 
with any unexpired file. The new label is 
then written into the VTOC. 

In case of CONSECUTIVE multirvolume 
files, one volume will be opened at a time, 
i.e., the second volume is opened when the 
last extent of the first volume has been 
processed, etc. Opening of the second and 



File Labels Ul 



following volumes is automatic. Thus, no 
explicit OPEN statement need be given. For 
all other files, all volumes will be opened 
at once. Therefore, all volumes to be pro- 
cessed must be mounted at the same time in 
this case. 

The handling of tape label information 
is similer. 



permanent ASSGN Command, The set of DLBL 
and EXTENT statements preceding the ASSGN 
command may contain only one EXTENT 
statement. 

The filename in the DLBL statement 
(which will be associated with the SYSxxx 
entry from the accompanying EXTENT state- 



Assignment of System Files to Disk 

In systems with at least 2UK positions of 
main storage, the system logical units SYS- 
IPT, SYSLST and/or SYSPCH may be assigned 
to an extent of 2311, 2314, or 2319 disk 
storage. 

It should be noted that the assignment 
of system files to disk requires operator 
intervention. For a complete description 
(also of ASSGN and CLOSE commands) refer to 
the SRL publication System/360 Disk Operat- 
ing, System Control and System Service Pro- 
grams, Order No. GC24-5036. 

The PL/I programmer should be aware of 
the fact that the PL/I standard files SYSIN 
and SYSPRINT are assigned to SYSIPT and 
SYSLST respectively. Since these files 
cannot be closed by the programmer and only 
one PL/ I file can be opened for one System 
logical unit on Disk at any one time, the 
use of GET or PUT statements without the 
FILE option should be avoided if there are 
user-declared files for SYSIPT and SYSLST. 
In order to avoid irapiied usage of SYSLST 
for comments as a result of error condi- 
tions, it is recommended to use the ONSYS- 
LOG option in the OPTIONS attribute of the 
MAIN procedure. 

The assignment of system logical units 
to disk storage drives must be permanent. 
The operator ASSGN command must be used 
instead of the programmer statement 
(// ASSGN). Temporary assignments (via the 
// ASSGN statement) to other device types 
are permitted. 

Note: The system generation parameter SYS- 
FIL is required to allow assignment of sys- 
tem logical units to a disk drive. 

System input and output files are 
assigned to disk by providing a set of DLBL 
and EXTENT statements and then submitting a 



IJSYSIN for SYSRDR, SYSIPT, or the 
combined SYSRDR/SYSIPT file SYSIN 

IJSYSPH for SYSPCH 

IJSYSLS for SYSLST 

In the DLBL statement, the codes operand 
must specify SD (or blank, which means SD) 
to indicate sequential DASD file type- 
In the EXTENT statement, type may be 1 
(data area, no split cylinder) or 8 (data 
area, split cylinder). There is no unique 
requirement for the remaining operands of 
the EXTENT statement. 

The ASSGN command must be one of the 
following: 

1. ASSGN SYSIN, X'cuu* (for a combined 
SYSRDR/SYSIPT file), 

2. ASSGN SYSRDR, X'CUU' (for SYSRDR only). 

3. ASSGN SYSIPT, X'CUU' (for SYSIPT only). 

4. ASSGN SYSPCH, X'CUU' (for SYSPCH). 

5. ASSGN SYSLST, X'CUU' (for SYSLST). 

Note that all roust be permanent 
assignments. 

System logical units assigned to disk 
must be closed by the operator. The opera- 
tor CLOSE command must be used to specify a 
system input or output file which has been 
previously assigned to a 2311, 2314, or 
2319. The optional second parameter 
(X'cuu') of the CLOSE command may be used 
(instead of an ASSGN command) to assign the 
system logical unit to a physical device. 
The system will notify the operator that a 
CLOSE is required when the limit of the 
file has been exhausted. If a program 
attempts to read or write beyond the limits 
of the file, the program will be terminated 
and the file must be closed. 
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// ASSGN SYS004,X'191' 



FILE 

'MY DEAR 

FILE' 



Volume label 
VOL12A 



Unit X'19T 




// EXTENT SYS004,VOL12A,„ 1000,210 



// DLBL FILEA/MY DEAR FILE' 



VTOC containing 

label of 

•MY DEAR FILE' 



r 



Object program 
UOCS table 

DC CLS'FILEA 






Pl/I source program 



DECLARE FILEA FILE 

UPDATE ENVIRONMENT 
(MEDIUM (SYS004,23n) 



I/O commands in LIOCS table control actual data transfer 

File information chain 
Information flow between VTOC and LIOCS table at open timed 



Figure 24, Program - Label Communication 
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Linkage Conventions 



The user of PL/I programs is not concerned 
with internal linkage durinq activation and 



ijc— a«^txvcitXGii uj. uxuuKii. 
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capability and/or efficieny of his program 
he may, however, wish to combine modules 
written in the PL/I Subset language with 
modules written in Assembler language. For 
example, the programmer may wish to make 
use of the checkpoint facility. Since 
there is no checkpoint facility in PL/I, 
the user may call a subroutine written in 
Assembler language. Calling of subroutines 
written in FORTRAN or COBOL is not 
permitted. 



Register Conventions 

Some registers may have to be used during 
the execution of the called program. The 
user must save the contents of these regis- 
ters by providing a save area. The address 
of the save area is contained in register 
13. The general registers involved in 
linking a called procedure to the main pro- 
gram are listed in Figure 25. Note that 
floating-point registers are not saved by 
the called subroutine. 
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Address of an argument list. 
This list contains the addresses 
of the arguments in the sequence 
stated in the argument (or para- 
meter) list in the CALL, PROCE- 
DURE, or ENTRY statement. Each 
argument requires one full-word 
on full- word boundary. In func- 
tion references, the argument 
list is immediately followed by 
the address of the field where 
the information computed by the 
subroutine is stored. 



H 



13 
14 



Address of the save area. 



Address to which the called sub- 
routine returns when execution 
has been completed. 



15 I Branch address, i.e., the 

address in the called subroutine 
to which control is transferred 
for execution. 



Figure 25. General Registers Used for 

Linking to a Subroutine Writ- 
ten in Assembler Language 



Note: If control is transferred from an 
Assembler routine to another PL/I subrou- 
tine, registers 7 and 8 must contain the 
same values as when control was trans- 
ferred to the Assembler routine. 



Calling 



Assume that register 13 has been set ear- 
lier in the program. To accomplish 
correct linkage, three additional regis- 
ters (1, 14, and 15) must be set. Regist- 
er 1 need not be set if no arguments are 
passed on and the call is not a function 
reference. The three different sequences 
that may be used to establish the required 
linkage between the main program and the 
called subroutine are shown in Figure 2 6. 

Note: The DOS/TOS macro instruction CALL 
may be used to facilitate programming in 
cases 2 and 3 shown in Figure 26. 



L 


15, =V( subroutine) 


BALR 


14,15 


CNOP 


2,4 


L 


15, =V( subroutine) 


LA 


14,*+6+4*n 


BALR 


1,15 


DC 


ACaddressl) 


DC 


A(address2) 


« « « 

DC 


A(addressn) 



L 15, =V( subroutine) 
L l,=AClistaddr) 
BALR 14,15 



listaddr DC 



A(addressl) 



Figure 26. Three Different Codings for 
Linking the Main Program and 
the Called Subroutine 



Saving 

Each calling program must provide a save 
area to store the contents of the general 
registers used by the called subroutine. 
When communicating with PL/I, the minirrum 
length of this area is 20 full-words (80 
bytes) . The area may be expanded for 
storing intermediate results or data of 
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Figure 27. Layout of the First 20 Words of the DSA of a Calling Program 



the storage class AUTOMATIC. This storage 
is called the DSA (Dynamic Storage Area), 



Ensure the addressability in case 
register 15 is destroyed during execu- 
tion of this module. 



Figure 27 shows the layout of the first 
20 full-words of the DSA of a calling pro- 
gram. Assume that register 13 contains 
the address of the first word of the DSA. 



The first instruction of a subroutine 
written in Assembler language must save 
the general registers lU, 15, 0, ,..,, 12. 
The DOS/TOS macro instruction SAVE can be 
used for this purpose. These registers 
must be saved even if their contents are 
not destroyed during execution of the sub- 
routine. Otherwise, ON- conditions that 
may occur might not be handled correctly. 
The next steps to be taken are: 

1. Store the contents of register 13 in 
word 2 of the subroutine save area. 

2. Ensure that word 3 of the save area of 
the calling PL/I program is not des- 
troyed by the Assembler subroutine. 

3. Set register 13 to the address of the 
subroutine save area. 



Returning 

Before returning control from the subrou- 
tine to the calling program, the contents 
of all registers must be restored. This 
is done as follows : 

L 13,4(13) RESTORES REG13 
LM 14,12,12(13) RESTORES REG14-12 
BR 14 

The last two instructions "may be replaced 
by DOS/TOS macro RETURN (14,12) 

The usage of LABEL parameters for 
returning from subroutines written in 
Assembler language necessitates a library 
call instead of a RETURN macro instruc- 
tion. Therefore, the address of the LABEL 
parameter must be loaded into register 1. 
The routine IJKSZCP must be ca:j.led next. 
The contents of register 13 are automatic- 
ally saved by this routine. Therefore, 
they must not have been changed 
previously. 
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The following example shows how a 
library call can be used to return from a 
subroutine written in Assembler language 
by means of LABEL parameters. 

L 1,8(3) 

* LOADS ADDRESS OF TABLE VARIABLE 
CALL IJKSZCP 

Note: The library subroutine IJKSZCN must 
be used to initialize the DSA if LABEL 
parameters are used. 

Correlation Between PL/I And 
Assembler Modules 

Modules written in the PL/I Subset lan- 
guage may call modules written in Assembl- 
er language and vice versa. However, if 
the program is combined of both PL/I and 
Assembler modules, one PL/I module with 
the attribute MAIM is required for correct 
initialization of the PL/I modules. Note 
that this MAIN procedure roust be the first 
module to be executed. 

Callina an Assembler Module 



fixed-point or decimal overflow condition 
as a SIZE error. If bit 7 is off, the 
condition is interpreted as FIXEDOVERFLOW. 

Note; Word 2 of the save area and regist= 
er 13 must be correctly initialized prior 
to the occurrence of any interrupt. 



Assembler Module Calling_PL/I _Modules 

Assembler modules that directly or 
indirectly call PL/I modules must provide 
a full DSA with a minimum of 20 full- 
words. This can be done by using the PL/ I 
library subroutine IJKSZCN, which creates 
the DSA and provides correct handling of 
register 13. The subroutine sets the 
words 1, 2, 3, 19, and 20 of the DSA, 
Word 20 accommodates the contents of 
register at the time when IJKSZCN was 
called. In internal PL/I procedures, this 
will be the address of the DSA of the 
statically embracing block. Word 3 con- 
tains the address of the storage location 
where IJKSZCN will construct the next DSA 
in case the present module calls another 



A module written in Assembler language is 
called according to the rules for calling 
external procedures either by means of a 
CALL statement or by means of a function 
reference. The Assembler module must 
satisfy all linkage rules given in this 
section. If the Assembler module does not 
call any other module, it must provide a 
minimum save area of two full-words. The 
4-byte field INDIC pointed to by bytes 1 
to 3 of the first word must contain the 
following information: 

Byte 3 contains the standard prefix 
option switches, whereas byte 2 contains 
the actual prefix option switches. If 
INDIC is not initialized by the library 
subroutine IJKSZCN, the contents of byte 3 
must be moved into byte 2 by the prologue 
of the module. The contents of byte 2 may 
be changed during execution of the module. 

Bits to 5 are used as switches with 
the following functions: 

ZERODIVIDE 

1 UNDERFLOW 

2 OVERFLOW 

3 FIXEDOVERFLOW 

4 CONVERSION 

5 SIZE 

If the respective bits are on (1) , the 
corresponding ON-condition is enabled. If 
they are off (0) , the ON-condition is 
disabled. 

If bit 7 is on, the PL/I interrupt- 
handling routine interprets a hardware 



Calling IJKSZCN destroys register 5. 
Therefore, register 5 should not be 
initialized by an Assembler module before 
IJKSZCN is called. IJKSZCN is called as 
shown below: 



LA 


1,PBL 


L 


15, =V( IJKSZCN) 


EALR 


14,15 



PEL is an 8-byte area con-taining the fol- 
lowing information: 

DS OF 

PEL DC X • 03 • 

DC AL3( INDIC) 

DC A (length) 

Note: Length is the length of the DSA in 
bytes. 

The calling sequence for IJKSZCN should 
be preceded only by the SAVE macro 
instruction and two LR instructions pro- 
viding for the addressability of the 



Passing Arguments 

The argument addresses in the argument 
list point to the first byte of the data, 
array, or structure to be passed on. The 
address of a V-type constant is passed for 
an ENTRY argument. The word following the 
V-type constant contains a pointer to the 
DSA of the block statically embracing the 
passed procedure if the passed procedure 
is internal. 
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Figure 28* Format of Call to Entry Parameter 



To allow for addressing of AUTOMATIC 
variables contained within the embracing 
block of an entry parameter, a call to the 
entry parameter should have the format 
shown in Figure 28, 



Use EXTRN statement in the Assembler 
modules. 

Case 2. Data items within Assembler 
modules which are referred to by PL/I 
modules: 



If FILE arguments are used, the address 
in the argument list points to the file 
appendage. In addition to the information 
in byte 0, the first word of the file 
appendage contains the address of the DTF 
table for this file* 

File arguments should be used very 
carefully in Assembler subroutines. Issu- 
ing an IOCS macro to a CCB which is part 
of a DTF table used by a PL/I program may 
destroy the synchronization between the 
PL/I program and logical IOCS. (Note that 
the CCB address must be inserted at object 
time when IOCS macros are used for file- 
name parameters.) However, a programmer 
experienced in DOS/TOS IOCS may use file- 
name parameters in Assembler subroutines 
to improve the capability of his program. 
For example, he may: 

1. change DTF tables to allow handling of 
additional user labels or non-standard 
tape labels before opening a file. 

2. change DTF tables to accomplish spe- 
cial stacker selection. PL/I programs 
use normal stackers for card input 
files and stacker 2 for punched- card 
output files. 

3. issue a CNTRL macro instruction for 
seeking on a REGIONAL file to allow 
overlapping of seek time. 

Figure 29 shows a PL/I procedure that 
calls a module written in Assembler lan- 
guage, which itself contains a function 
reference to another external PL/I 
procedure. 

Data of the scope EXTERNAL may be 
shared between PL/I and Assembler modules. 



Case_l. Data items within PL/I modules 
which are referred to by Assembler lan- 
guage modules: 



Each data item must be a separate CSECT; 
otherwise incorrect addresses will be 
assigned when the programs are 
link- edited. 

If a data item is a structure, all its 
individual elements can be coded together 
as a series of DCs or as a DS in the 
Assembler- language module under a single 
CSECT. In preparing such a structure, the 
PL/ I structure mapping rules as described 
under Data storage_Mapping must, however, 
be observed. 

The CSECT statement must be used if the 
respective name is not declared to be 
EXTERNAL in any PL/I program within the 
same phase. In all other cases, the pro- 
grammer may use the instruction he consi- 
ders convenient. 

Note: Values returned by routines written 
in Assembler language must have the format 
specified for PL/I. Floating-point data 
must be normalized. 



Checkpoint And Restart 

A typical example for a procedure written 
in Assembler language is checkpointing and 
restarting. For convenience, both the 
checkpoint part and the restart part 
should be contained in the same routine. 

If checkpointing is desired, the 
restart address, the end address, and the 
tape file positioning information must be 
provided. vSome additional information is 
required if the checkpoint is to be writ- 
ten on disk.) The restart address is 
known if it is in the same module as the 
checkpoint routine. The end address can 
be taken from word 3 of the save area, 
since this is the address of the next (not 
yet allocated) save area. Names of tape 
files can either be passed as parameters 
or addressed directly by using a V-type 
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constant. (See the discussion on file 
parameters in the section Passing . Argu- 
ments. The same applies to the usage of 
V-type constants = ) 

After the job has been restarted with 
the RSTRT statement, the restart routine 
must issue an STXIT macro for Program 
Check Interruption* The two address 
operands to be issued with STXIT are the 
external names IJKSZCI and IJKZWSI for the 
routine address and the save area, resoec- 



tively. i^oreover, the program mask must 
be reset. 



Note: PL/I input files must not contain 
interspersed checkpoint records. 



sTt .-rn TCS "^fi =!-..-it.TO 






figure 30 snows a couing example or a 
routine combining the checkpoint and the 
restart part. For detailed information— 
refer to the following SRL publications: 



// EXEC 


Pl/I 






CALLER: 


PROCEDURE 


OPTIONS (MAIN); 






DECLARE C CHARACTER (25) STATIC; 






CALL SUBASM (4,B,C) /* CALLS SUBROUTINE WRITTEN IN ASSEMBLER LANGUAGE */; 




END; 






/* 








// EXEC 


ASSEMBLY 








TITLE 


'SUBROUTINE CALLED BY Pl/I AND CALLING Pl/I' 


SUBASM 


START 





PARAMETERS ARE A, B, C 




USING 


*,9 






SAVE 


(14,12) 


SAVE REGISTERS 




LR 


9,15 


ASSURE PROGRAM ADDRESSABiLiTY 




LR 


3,1 


ASSURE ADDRESSABILITY OF PARAMETERS 




U 


1,PBL 


CREATE OWN DSA 




CALL 


IJKSZCN 






L 


1,0(3) 


MAKE A ADDRESSABLE 




LE 


0,0(1) 


LOAD A 




L 


1,4(3) 


MAKE B ADDRESSABLE 




AE 


0,0(1) 


ADD B 




CALL 


LEVEL3,(X,Y, RETURN) 


CALL Pl/I FUNCTION PROCEDURE 




i. 


1,8(3) 


MAKE C ADDRESSABLE 




MVC 


0(24,1), RETURN 


C * RETURN if '.'; 




MVI 


24(1),X'4B' 






L 


13,4(13) 






RETURN 


(14,12) 


RETURN TO CALLING Pl/I PROCEDURE 


X 


DS 


F 


ARGUMENT X 


Y 


DS 


CL3 


ARGUMENT Y 




DS 


OF 




PBL 


DC 


X'03' 


DATA TO CREATE DSA 




DC 


AL3(ON INDICT) 


POINTER TO ON-INDICATOR WORD 




DC 


20A 


20-WORD DSA 


ONINDICT 


DC 


3X'0' 






DC 


B'l 11 10000' 


SIZE AND CONVERSION DISABLED 


RETURN 


DS 


CL24 


SPACE FOR RECEIVING STRING FROM 


* 


END 




Pl/I FUNCTION LEVEL3 


A 








//EXEC 


Pl/I 






LEVEL3: 


PROCEDURE (U,V) CHARACTER (24); 






DECLARE STR CHARACTER (21), V FIXED DECIMAL (5,2); | 




RETURN C^ 


»' 11 STR) 


/* ONE BUNK AUTOMATICALLY 
ADDED AT THE END TO OBTAIN 








CORRECT LENGTH */; 




END; 






/* 









Figure 29, Example of Linkages between PL/I Procedure and Assembler Module 



US 



For_DOS 

IBM Systetn/360 Disk Operating System, Sys- 
tein Control and System Service Programs, 
Order No, SC24-5036 



For_TOS 

IBM System/360 Tape Operating System, Sys- 
tem Control and System Service Programs, 
Order No. GC24-5034 



IBM System/360 Disk Operating System, 
Supervisor and Input/Output Macros, Order 
No. GC2^4-5037 



IBM System/ 360 Tape Operating System, 
Supervisor and Input/Output Macros, Order 
No. GC24-5035 



CPRS 


TITLE 


'CHECKPOINT-RESTART ROUTINE' 


* 


' 


CALLED BY A Pl/I PROCEDURE. THE INFORMATION ON THE 


* 




POSITIONING OF THE TWO FILES TAPEIN AND TAPEOUT IS 


* 




TO BE CHECKPOINTED 


. 


CHPRES 


START 








USING 


M2 






SAVE 


(14,12) 






LR 


12,15 


SET BASE REGISTER 




LA 


l',PBL 


CALL Pl/I PROLOGUE ROUTINE 




L 


15,^(IJKSZCN) 






BALR 


14,15 






L 


2,=VaAPEIN) 


PREPARE FILE TABLE 




L 


2,0(2) 






ST 


2,FILETAB+2 






L 


2,=V(TAPE0UT) 






L 


2,0(2) 






ST 


2,FILETAB46 






L 


2,8(13) 


LOAD END ADDRESS 




BALR 


3,0 


SAVE PROGRAM MASK IN AUTOMATIC 




ST 


3,80(13) 


STORAGE 




CHKPT 


SYS007, RESTART, (2), TPOINT CHECKPOINT ON SYS007 | 




B 


RETURN 




* 






RESTART PART. NOTICE THAT ALL GENERAL 


* 






REGISTERS ARE AUTOMATICALLY RESTORED. 


RESTART 


L 


0,=V(IJKSZCI) 


SET PROGR. CHECK INTERRUPTION EXIT. 




L 


1,=V(UKZWSI) 






STXIT 


PC,(0),(1) 






L 


2,80(13) 


SET PROGRAM MASK. 




SPM 


2 




RETURN 


L 


13,4(13) 


RETURN TO Pl/I CALLER 




RETURN 


(14,12) 






DS 


OF 




PBL 


DC 


X'03' 


ARGUMENT FOR IJKSZCN 




DC 


AL3(INDIC) 






DC 


22A 


Pl/I SAVE AREA DEFINITION + 1 WORD FOR 


* 






SAVING PROGRAM MASK (MUST BE MULTIPLE 


* 






OF EIGHT). 


INDIC 


DC 


A(0) 


ON INDICATORS 


TPOINT 


DC 


A(FILETAB) 


POINTER TO FILETABLE 




DC 


A(0) 


PIOCS FILES NOT USED 




CNOP 


2,4 




FILETAB 


DC 


H'2' 


FILE TABLE 




DS 


2F 






END 







Figure 30. Coding Example of Combined Checkpoint and Restart Routine 
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General Programming Information 



This section describes some programming 
techniques to save storage, produce a 
faster object progranif perforin functions 
not easily achieved with more conventional 
PL/I language facilities, make a program 



If a program uses the entire storage 
and no space is left for eventualities. 






J i ^.C ^ 1 J- 



If, however, normal expansion was provided 
for, the overall job is much easier* 

CONVERSIONS 



STATEMENT_FORMAT 

The first column of every source text card 
must be blank. Columns 73-80 are ignored; 
they may contain any information. 



PROGR^M_SEGMENTATigN 

Every program should be written so that it 
can be segmented if necessary. The case 
of storage overflow should be provided for 
so that, if it does occur, it can be 
handled easily. Breakpoints in the logic 
of a program, i.e., points where a program 
phase can be terminated and a subsequent 
phase entered, should be numerous. 

Data common to successive programs can 
be kept through the proper use of the 
EXTERNAL attribute. However, not all data 
need be external. 

Programs that read data, compute, and 
write results lend themselves to segmenta- 
tion most readily, wherever practical, 
entire programs should be written as 
sequences of calls for subroutine proce- 
dures because each call is a logical brea- 
kpoint. Thus, the entire storage can be 
loaded with as many subroutines as can be 
accommodated. The next phase then repeats 
the process of loading the storage with 
the next group of subroutines, etc. 



PROGRAM_EXPANSigN 

In general, no more than 90 % of the 
storage available for any program phase 
should be used during the first six months 
of its life because, at one time or anoth- 
er, every program tends to expand due to 

1, programming errors, 

2. the need to expand the original 
function. 



3, errors in the system program or 
associated subroutines, and/or 

4. an increase of the data storage 
requirements. 



the 



If a numeric variable is to be used fre- 
quently in expressions, it is much more 
economical to convert the variable to 
coded form once and use the coded form in 
all expressions. This is easily done by 
'— =~- "-^ an assignment statement- 



luirciiis us. 



Conversions implicit in I F statements 
follow the rules for arithmetic conver- 
sions, and the intermediate precisions 
should be considered when using such 
expressions. 

For example, in case 3 (IF X=U THEN ) 

of the following sample program the conv- 
ersion rules are applied to X, giving a 
shdrt- precis ion floating-point number 
which is then expanded (padded) with 
trailing zeros to long precision before 
the actual comparison operation. Thus 
expression 2 will be executed, not expres- 
sion 1. However, if X and U are assigned 
with a value which will be the same in 
both short and long precision (e.g. 0.5), 
then expression 1 will be executed. 

In evaluating the following program, 
refer to Section F: Data_Ccnversion in 
l§M_System/360, Disk and Tape Operating 
Systems, PL/I Subset Referen ce M anual , 
Order No. 0028-8202."" 



PROCEDURE OPTIONS (MAIN) 

DECLARE X DECIMAL FIXED 

DECLARE T DECIMAL FIXED 

DECLARE Y FLOAT (6); 

DECLARE U FLOAT (16) ; 

X=123.45 

Y=123.45 

T=123,45 

U=123.U5 

IF X=Y THEN expression 

ELSE expression 
IF X=T THEN expression 

ELSE expression 
IF X=U THEN expression 

ELSE expression 
IF Y=T THEN expression 

ELSE expression 
IF Y=U THEN expression 

ELSE expression 
IF T=U THEN expression 

ELSE expression 



(5,2); 
(15,2) 



1 


/* 


Yes */ 


2 


/♦ 


No */ 


1 


/* 


Yes */ 


2 


/* 


No */ 


1 


/* 


No */ 


2 


/* 


Yes */ 


1 


/♦ 


No */ 


2 


/* 


Yes */ 


1 


/+ 


No */ 


2 


/* 


Yes */ 


1 


/* 


Yes */ 


2 


/* 


No */ 



END 
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For an example showing the conversion 
of characters into binary numbers, refer 

to A2£endix_L^ Programroin cf E xamples , 

"Conversion of Numbers in Character Form 
Into Binary Numbers". 



ySE_gF_UNSPEC 

The QNSPEC pseudo variable and the UNSPEC 
built-in function handle the internal 
representation of data. The internal 
representation of data is summarized in 
Figure 50 and described in detail in the 
section Data Storage Requi rem ents. 



The programmer must make sure that 
values assigned by the UNSPEC pseudo vari- 
able have the correct format. Otherwise, 
the results are unpredictable. Note that 
the internal representation of floating- 
point data is normalized. Consider the 
following example: 



DECLARE A FLOAT, B CHARACTER (1 ) , C FIXED 

DECIMAL (5, 3); 
B— o f 

X: POT EDIT (UNSPEC (B)) (SKIP,B); 
Y: UNSPEC (A) =(31) 'O'S i| 'I'B; 
Z: UNSPEC(C)=(16yO'B || 'OllOOOOO'B; 






























^1 ROOT 
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w 






'f 
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Phase 1: 




Phase 2: 




Phase 3: 


Opens files. 
Performs input. 
Closes files. 




Computation 




Opens files. 
Performs output. 
Closes files. 



Figure 31. 



BLOCKING 



Example of Using Overlays tc 
Perform Computations and I/O 
Operations Separately 



It may happen that one large set of data 
is used in a program only at one specific 
point, that another large set of data is 
used at another point, etc. In this case, 
each set of data used at one point should 
appear in a separate block so that the 
data is AUTOMATIC by default (unless de- 
clared to be STATIC) and allocated only 
when the respective blcck is active,. 
Thus, th« same storage area can be used 
for all data sets to be used. 



The result of statement X is 11111000. 
Statement Y yields unpredictable results 
since the value to be assigned is not nor- 
malized. Statement Z also yields lanpre- 
dictable results since the last half -byte 
does not contain a valid sign for packed 
decimal data representation. 



For an example of the UNSPEC built-in 

function, see Appendix L. Programming 

Examples, "Conversion of Numbers in 
Character Form to Binary Numbers". 



SIMULATION OF P-FOR MAT ITEMS 

The PICTURE- foimat items of OS PL/I are a 
more powerful tool for editing than the 
format items available in DOS/TOS PL/ I. 
However, numeric fields in edit-directed 
I/O operations can easily be simulated by 
overlaying numeric fields with character 
strings using the DEFINED attribute. An 
example is shown below: 

DECLARE U PICTURE ' $$, $$9 . V99BCR' , 
B CHARACTER (12) DEFINED U; 



U= ... 

PUT SKIP EDIT CU = 



B) (2 A); 



COMPUTATIONS WITH OVERLAY 

Whenever possible, input/output phases 
should be performed separately from compu- 
tational phases. Thus, the I/O subrou- 
tines including the E and/or F conversion 
subroutines are never in storage simul- 
taneously with the other subroutines (ari- 
thmetic, base, and scale conversion, 
etc. ) . This can result in considerable 
storage savings (see Figure 31) . 



SIMULATION OF ARRAYS OF STRU CTURES 

Since arrays of structures are not per- 
mitted in the PL/I Subset language, it is 
recommended to simulate arrays of struc- 
tures by using arrays in structures, i.e., 
by arrays that are not themselves struc- 
tures. Should this not be feasible, 
arrays of stmctures may be simulated by 
using based structures. This can be 
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accomplished by assigning to the pointer 
the value of an element of a character- 
string array. The programmer is respons- 
ible for satisfying all boundary 
requi r ements . 



The following example shows the handl- 

•inrr o-F ej-Hr-nr-HiTr-oc: -in n.C: DT./T TTOT-anc: nOQ/ 



TOS PL/I: 



Uti fli/X 



DECLARE 1 A, 2 B FLOAT, 2 C(10), 3 D 
PICTURE '9999*, 
3 E PICTURE *XX', 
3 F PICTURE •99V99'; 



The use of the DEFINED attribute can 
result in considerable savings of storage, 
This is obvious for arrays, e.g., the 
statement 



DECLARE A (5,9,7),, B (5,9,7) DEFINED A; 



merely requires the storage area for array 
A (315 data items). Without the DEFINED 
attribute, the storage requirements would 
be twice as much. But in spite of the 
more severe restictions on the use of the 
DEFINED attribute for structures, it can 
also be of considerable use in this case. 



.-\/-\ X — 1 mr\ 1 A 



A.D(I) = . 



END; 



This could be written in DOS/TOS as 
follows: 

DECLARE PTR POINTER, 1 A, 2 B FLOAT, 2 C 
(10) CHARACTER (10), 1 X BASED 
(PTR), 2 D PICTURE •9999', 2 E 
PICTURE 'XX', 2 F PICTURE '99799'; 



not? r>T? nTiOTpi^ tta tdttitdt 170 r-TTrnti om-Dnz-TnTTn-pc? 



KJKJA^ yyx 



xjriiuj^jL/ 



ix\a.ni^j-.uo >ixj 



ox r\u^x urvxio 



The restrictions on the use of the DEFINED 
attribute for structures can be circum- 
vented by using based variables instead of 
the DEFINED attribute. For example, in 
the statement shown below structures U and 
I are based variables. They are never 

pointer variable P can be used to utilize 
the storage occupied by structure A 
whenever "structures U and I are referred 
to (provided that structure A is not 
required at the same time) . 



DO 1=1 to 10; 

xn— rtUUh. \rt. 



DECLARE P POINTER, 



<«- \x/ / 



n njLi±>jL*£^u I 



X.D=. ... 



END; 



USE OF THE DEFINED ATTRIBUTE 

For scalar variables or arrays, the 
DEFINED attribute is used when 

1. a variable is to have more than one 
name (correspondence defining) , or 

2. two separate variables are to occupy 
the same storage area provided they 
are never required simultaneously 
(overlay defining) . 

In either case, the actual storage 
requirement is that of the base identifier 
and not the sum of the storage require- 
ments of all variables. For restrictions 
on the use of the DEFINED attribute for 
scalar variables and arrays see the Subset 
language publication. 



2 


B 


BIT(7), 






2 


C 


FIXED DECIMAL (13, 


2), 


2 


D 


CHARACTER 


(21), 




U 


ALIGNED BASED (P), 




2 


V 


BINARY, 






2 


w, 








2 


X 


BIT(19), 






I 


EASED (P), 






2 


J. 








2 


K, 








2 


L; 









The statement 

P = ADDR (A) ; 

would cause any subsequent reference to 
either U or I or any corrpcnent of U or I 
to point to the storage area occupied by 
A. This simulates the use of the DEFINED 
attribute with all of its restrictions 
removed except that the based structures 
must be mapped in the same or less storage 
than the map of the overlaid structure. 
This process may be extended even further 
so that a based variable structure occu- 
pies the storage area of any one of many 
structures. This is deironstrated below: 
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DECLARE (V1,V2) POINTER, 

1 A, 2 B, 2 C, , 

1 U ALIGNED, 2 F, 3 Q BIT (9),.,. 

1 R, 2 Z, 2 M, 3 S CHARACTER (2),, 

1 PI BASED (VI), 2 L, 2 X,.,., 

1 P2 ALIGNED BASED (V2) , 

2 D BIT(9),.; 

V1=ADDR(A) ; 

using PI here points to A 
V1=ADDR(U); 

using PI here points to U 
V2=ADDR(R); 

using P2 here points to R 

V1=ADDR(R); 

using PI here points to R 
etc. 



Of course, the storage requirement of 
structure PI must not exceed that of the 
smallest of either A, U, or R. Since the 
structure P2 does not point to A or U in 
this procedure, the only prerequisite is 
that its storage requirement must not 
exceed that of R. 

Note on Compatibility: The structure- 
mapping technique for OS PL/I is identical 
to that for DOS/TOS PL/I in every respect 
but one. The exception is that DOS/TOS 
PL/I causes all structures to begin at 
double-word boundaries. This is accomp- 
lished by padding to the left of the first 
addressable element until byte zero is 
reached. (See the section Structure Map- 
ging_Rules, rule 11.) 

OS PL/I begins structures at the first 
addressable element- This difference is 
of no significance in PL/I programming 
unless the above-described technique is 
employed. When this technique is used, 
compatibility is guaranteed if at least 
one element of the non-based structure has 
a stringency level that is as high as that 
of the element (or elements) of the high- 
est stringency level of the based 
structure. 

For the D Compiler the pointer asso- 
ciated with a based structure must be 
assigned an address value which insures 
that the first element of the structure 
has the same distance to a double-word 
boundary as it would have if the structure 
was not based. 

Note: The use of based structures to 
avoid the use of the DEFINED attribute is 
dependent on structure mapping which, in 
turn, is implementation-defined. 



REDEFINITION OF ATTRIBUTES 

The two preceding sections showed that a 
number of structures can be made to occupy 
the same storage area- Similarly, a 
single character-class variable may be 
conceived of in many different ways. Con- 
sider the declaration shown below. 

DECLARE A CHARACTER (80), 

1 B DEFINED A, 

2 C CHARACTER (40), 

2 D CHARACTER (30), 

2 E CHARACTER (10) , 

1 F DEFINED A, 

2 G PICTURE M8)9', 

2 H PICTURE '9*, 

2 I CHARACTER (61), 

2 J PICTURE M5)9V(5)9', 

1 K DEFINED A, 

2 L (10) PICTURE '$$(4)97(2)9'; 

A represents a string of 80 characters 
whereas B,, F, and K represent three dis- 
tinct structures. However, these three 
distinct structures refer to the same 
storage area as A. This technique is 
especially useful in programs with many 
different structures to be read. Fca: 
instance, the program may read a character 
string and, depending on its first 
character, treat it in any one of many 
different ways without requiring space for 
each possible structure- 



USE OF THE 48-CHARACTER SET 

If the 48-character set is used, the word 
PT, in addition to those listed in the 
Subset language publication, is a reserved 
keyword. Programs written in the 60- 
character set can be read if 48C is speci- 
fied in the OPTION statement (but not vice 
versa) . 



SIZE OVERFLOW 

If a size overflow occurs during F-format 
output, the output field will contain 
asterisks, even if SIZE is disabled. 



USE OF THE DISPLAY STATEMENT WITH THE 
REPLY OPTION 

Using the DISPLAY statement with the REPLY 
option is possible only if a 1052 Printer- 
Keyboard is available. 



PRECISION OF DECIMAL DATA 

The use of an odd precision for decimal 
data will keep the generated code at a 
minimum and thus improve the program 
performance. 
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CHANGING_THE_TAB_CONTRgL_TABLE 

List- directed output to PRINT files auto- 
matically aligns data on preset tab posi- 
tions. For the D- level compiler, these 
tab positions are 1, 25, 49, 73, 97, and 
121. 

The tab positions are determined from 
the control table IJKTLTB which is catalo- 
gued under this name in the relocatable 
library. To obtain different tab posi- 
tions, the programmer only has ta change 
this table by specifying the following 
macro instruction: 

IJKZL (tab, [tab,.,.,] FF) 

In this macro instruction, 'tab' is a 
decimal constant indicating the desired 
tab postion, and *ff* indicates the end of 
the table. Tabs must be specified in 
ascending sequence, and their values must 
range between 1 and lt4. The length of 
the tab list specified in the IJKZL macro 
instruction must not exceed 127 charac- 
ters, including opening and closing paren- 
theses and commas . 

Following is an example of the IJKZL 
macro instruction and the control state- 
ments required to change the tab settings. 



DO var = expl TO exp2 [BY exp3] 
[WHILE (exp4) ] ; 

'var' is a fixed binary value, all con- 
stants used as expl, exp2, and expB will 
be converted to fixed binary during compi- 
lation, in order to avoid conversions dur- 
ing execution. 



gQPMDING_ON OUTPUT, WITH E AND F FORMAT 
ITEMS 

On output, data edited by the E- or F- 
format are rounded at the last numeric 
position, and not truncated. 



HANDLING BLANK NUMERIC FIELDS 

When using a PICTURE specification with 
•9*s for numeric fields and the field is 
clank, a program check (data exception) 
occurs. 

This is a particular problem for card 
input where fields are often left blank 
rather than filled with zeroes. 



// JOB IJKTLTB 
// OPTION DECK 
// EXEC ASSEMBLY 

IJKZL (1,25, 50, 75, 100, FF) 

END 
/* 

* THE RESULTING OBJECT DECK IS INPUT 

* FOR THE FOLLOWING EXEC MAINT PROGRAM 
// EXEC MAINT 



(Object deck) 



/* 
/6 



If the specified tab positions do not fall 
between the values 1 and mu, or if they 
aire not in ascending sequence, one of the 
following messages is issued: 

PARAMETER GT It* 4 

PARAMETER NOT IN ASCENDING ORDER 



The problem can be avoided by declaring 
the field with PICTURE using ' Z' rather 
than '9' or with PICTURE using '9' plus 
one of the overpunch picture characters T, 
I, or R, 

Assume card columns 1-10 are numerical 
and may or may not be punched. 

DECLARE C0L_1 PICTURE '(10)9'; 
DECLARE C0L_1 PICTURE '(lO)Z'; 
DECLARE C0L_1 PICTURE '(9)9(1)1'; 

The first DECLARE statement causes a 
data exception if the field is blank. No 
data exception occurs for blanks in 
columns 1 through 10 if the field is de- 
clared as shown by the second and third 
DECLARE statements. 

The programmer should, however, be 
aware that the exclusive use of '9's in a 
PICTURE specification results in more 
efficient code. 



IMPRgVEMENT_QF_DO-LOOPS 

The execution time of a DO- loop can be 
reduced if a fixed binary variable is used 
as control variable in the DO statement. 

For example, if in the statement 



USE OF LIST-DIRECTED AND EDIT-DIRECTED 
DATAJTRANSMISSION 

When the list-directed and edit-directed 
transmission modes are used for the same 
file, the user is responsible for the 
correct positioning of the file. 
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USS OF PICTURES WITH STREAM- ORIENTED DATA 
TRANSMISSION 

1 • Character-string pictures; 

The D Compiler handles them in the 
same way as normal character- string 
variables, 

2 • Arithmetic pictures: 

All kinds of arithmetic pictures are 
possible in the data lists of GET and 
PUT statements. 

a. Edit-directed transmission: 

Only such items in the data stream 
which can be described by the E or 
F format can be transferred from 
(PUT) or into (GET) arithmetic 
pictures. If, on output, the pro- 
grammer wants the character repre- 
sentation of the picture, he 
should use the CHAR built-in func- 
tion as pseudo-variable with the 
picture as argument in the data 
list. 

b. List-directed transmission: 

On input, only [+|-] arithmetic 
constants can be transferred into 
arithmetic pictures. On output, 
the character representation will 
be transferred into the data 
stream. 



(a) If the first fractional digit 
position is the first '9* in the 
field, then 

•'ZZ,ZZZV.99' is better than 
*ZZ,ZZZ.V99'. 

(b) If a drifting character or zero- 
suppression is specified past the 
decimal point, then 
'$$$$$V.$$' is better than 
•$$$$$. V$$' 

•*****V.**' is better than 
• *****. V**' 

3. Give the variable in the right-hand 
side of an assignment statement the 
attribute DECIMAL FIXED with the same 
scale and precision as the PICTURE. 
If there is an expression on the 
right-hand side try to produce the 
desired scale and precision, 

4. Zero-suppression with "*" costs more 
storage (code) than zero-suppression 
with "Z" if 

"+" or "-" is used (static or drift- 
ing) or 

"B" is used after the last digit 
position, 

5. If the PICTURE does not contain at 
least one "9", "T", "I" or "R", but 
does contain a "V", additional code is 
required for clearing the field in 
case of a zero value,. 



PICTURE SPECIFICATIONS 



Storage can be saved by proper declaration 
of fixed numeric PICTURE fields. 

1. PICTURE specifications without drift- 
ing characters: make the first digit 
position 'Z' or '*' and avoid writing 
the first '9' in the field immediately 
following an insertion character. 

'Z9,99,V99' is better than '99,99.V99' 
•SZZ9999' is better than •S999999' 
'+ZZ,Z999' is better than •+ZZ,9999' 

2, Specifying "V." rather than " ,V" 
results in better code in the follow- 
ing cases: 



ENDPAGE WITH MULTIPLE-LINE PUT 

When using a PUT statement producing mul- 
tiple lines, the ENDPAGE condition should 
not be enabled because of possible loss of 
data: 

ON ENDPAGE (F) GOTO X; 

PUT FILE(F) EDIT (data-list) (format-list) ; 

X: new header; 

In this example the ENDPAGE condition 
may be raised during execution of the data 
list (assuming multiple-line output) ; but 
no return from X is possible, so that the 
rest of the data list will be ignored. 
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Program -Checkout Facilities 



Certain language features are provided in 
PL/I to assist the prograrniner in debugging 



Trie: m-rr\rrmm 



Thtacs^i ■p3/-«T 1 T -l-T i 



described below. 

For a detailed discussion of how to 
debug a PL/ I prograroj refer to the section 
Debugging PL/I Programs in the SRL publi- 
cation IBM Systeni/360 D is k Operating Sys- 
tern,^_SYStem Programmer '_s Guide, GC2 U- 5073 . 



Exhibit Changed 









library routine IJKEXHC which reguires 
approximately 1200 bytes of main storage. 

In addition, each variable appearing in 
a CALL IJKEXHC statement reguires about 12 
bytes of storage plus a field containing 
the variable name plus a field containing 
the value of the variable in static 
storage. 

Function: 

The first execution of the CALL IJKEXHC 
statement causes the printing of the names 
listed in the statement, and their values 
in hexadecimal notation. 

General Format: 

CALL IJKEXHC (name , name ....); 

The argument 'name' can be an unsub- 
scripted, ungualified name representing an 
element, an array, or a structure which 
are not contained in an array or struc- 
ture, or it can be a string or arithmetic 
constant. However, it cannot be a label 
constant, an entry name, or a file name. 

General Rules: 

1, Names with the attribute AUTOMATIC are 
printed each time the CALL IJKEXHC 
statement is first executed after a 
new block activation. Names with the 
attribute STATIC are printed only the 
first time the CALL IJKEXHC is 
executed if the activated block is 
internal. They are printed each time 
the CALL IJKEXHC statement is executed 
if the activated block is external. 

2 . On subsequent passes of the CALL 
IJKEXHC statement, the names and 
values are printed only if the value 
has changed since the time the state- 
ment was last executed. 



3. If there are several CALL IJKEXHC sta- 
tements in one program, thev are inde- 



4. The maximum number of arguments for 
one CALL IJKEXHC Statement is 12. If 
an argument has the BASED or DEFUSED 
attribute, the related pointer or base 
variable is counted as an argument, 
regardless of whether it has been spe- 
cified in the argument list or not, 

5. Up to 30 names can be checked by CALL 
IJKEXHC statements within one block, 
if lOK bytes are available to the com- 
piler. For each additional UK, up to 
46K, 30 additional names can be 
checked. 

6. The values of element variables having 
the attributes BINARY FIXED, BINARY 
FLOAT, DECIMAL FIXED, DECIMAL FLOAT, 
CHARACTER, BIT, or PICTURE are also 
printed in their external form. 



Tracing 

The TRACING feature uses the library rou- 
tine IJKTRON which requires 1258 bytes of 
main storage. 

In addition, about 3U bytes of storage 
are required for each CALL IJKTRON state- 
ment and about 12 bytes for each CALL IJK- 
TROF statement. 

Function: 

The two statements, CALL IJKTRON and CALL 
IJKTROF, function like a switch. IJKTRON 
switches tracing on, while IJKTROF turns 
it off. 

If tracing is enabled for a block, the 
following information is printed on 
SYSLST: 

1. On entry, the external name of the 
block, or, if the block has no label, 
the internal name of the block. 

2. On leaving a block via an END or 
RETURN statement, a message is given 
to indicate the exit. If the STMT 
option is active, the statement number 
of the END or RETURN statement is 
printed as well as the number of the 
statement to which the program 
returns. 

Note: If for 'CALL entry name' infor- 
mation should be printed, tracing must 
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be enabled for the block which con- 
tains the entry name. 

3, For each executed GOTO statement 

a. the external name (up to eight 
characters) and value of the label 
variable or constant if the GOTO 
statement is not in an on-unit, or 

b. the ON-condition and the value of 
the label variable or constant if 
the GOTO statement is in an 

on- unit. 

If the STMT option is active, the sta- 
tement nuirber of the GOTO statement 
and the statement number of the target 
statement are also displayed. 

General Format : 



4) 


Ml: 


CALL Bl; 


5) 




C=3; 

• 


6) 




GOTO A2; 


7) 




A2: BEGIN; 

• 


8) 




CALL IJKTROF; 


9) 




• 

GOTO A 21; 



10) 



A21: CALL IJKTRON; 



CALL IJKTRON; 
CALL IJKTROF; 

General Rules ; 

1. Tracing can be explicitly enabled in a 
block by a CALL IJKTRON statement. 

2. A CALL IJKTROF Statement explicitly 
disables tracing in a block. 



If tracing is neither explicitly 
enabled nor disabled in a block, the 
tracing status of the dynamically con- 
taining block is applied. 



The dynamically containing block of 
the main procedure has tracing 
disabled. 



5. At least one of the two statements has 
to be specified if tracing is to 
appear in an external procedure. 

6. When calling an external procedure 
(provided tracing is enabled at the 
time of the call) , the called phase 
must have a call for either IJKTRON or 
IJKTROF. If this condition is not 
satisfied, the results are unpredict- 
able in the event of an interrupt. 



Exampl e : 

1) Al: PROCEDURE OPTIONS (MAIN); 

2) CALL IJKTRON; 

3) GOTO All; 



11) END A2; 



12) END Al; 

13) Bl: PROCEDURE; 



14) 



15) 



16) 



CALL IJKTROF; 



RETURN ; 



END Bl; 



This example causes the following (the 
statement numbers in the above example are 
referenced in the left-hand margin below) : 



1) When the main procedure is invoked, 
no tracing status is specified and, 
therefore, tracing for this block 
and, per definition, for the dynam- 
ically containing block is 
disabled. 

2) Tracing is explicitly enabled in 
block Al. 

3) The external name and value of 
label All are printed. 

4,13) No tracing status is specified for 
this block; therefore, the 
(enabled) status of the containing 
block Al is adopted and the name of 
the procedure Bl is printed. 

14,15) Tracing is explicitly disabled for 
this block, and no message is 
printed when control returns to 
statement 5. 

6) The external name and value of the 
label A2 are printed since tracing 
is still enabled in Al. 
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7) With the activation of block A 2 

tracing is neither enabled nor dis- 
abled, therefore the (enabled) sta- 
tus of block hi is adopted and the 
external name of block a2 is 
printed. 

8,9) Tracing is disabled for block A2 
and no message is printed^ 

10,11) Tracing is again enabled and the 

pass of the EtvD stateinent is indi- 
cated on SYSLST, 

12) Since tracing in the main routine 
is still enabled, the pass of this 
END statement is also indicated on 
SYSLST. 

The DYNDUMP Routine 

The statement 

CALL DYNDUMP (argument- list) ; 

may be used to have the internal represen- 
tation of the items in the argument list 
displayed in hexadecimal notation. The 
argument list may contain up to 12 items. 
Each argument must be either a scalar 
expression or a variable name. 

The DYNDUMP routine (56 bytes in 
length) uses the PL/I Control routine and 
the SYSPRINT file with the associated 
module. No additional I/O subroutines are 
required. Thus, the DYNDUMP routine pro- 
vides an economical way of displaying 
intermediate results during checkout of 
PL/I programs with a minimum of library 
and I/O module overhead. 

The following example shows the use of 
the DYNDUMP routine, 

DECLARE A FIXED(5,2), B(10), C BIT(l); 



CALL DYNDUMP (A,B,C); 

Three items are displayed: A as 3 
bytes (6 hexadecimal digits) , B as 40 
bytes (80 hexadecimal digits), and C as 
one byte (2 hexadecimal digits). 

Note: The current value of C is indicated 
by the first bit. If the variable length 
is an exact multiple of 48 bytes, the end 
address+1 will be printed on the next line 
in order to delimit the variables for ease 
of reading. 



Locating Execution-Time Errors 

If a PL/ I object program is terminated by 
the PL/I Control routine and the DUMP 
option is active, the problem program area 



is printed (dumped) on the device assigned 
to SYSLST. The following information is 
intended to assist the programmer in ana- 
lyzing a program dump and to locate the 
error that caused the termination of this 
program. 



1/-. /~rlf:=-r-r^-n*-r^^ *. X^ — X. 



ija I, ii;cij.iJ 



Note: Ther< 
storage organization will always be as 
described below. Severe programming 
errors, e.g., illegal use of based 
variables J the UNSPEC pseudo variable, or 
use of user-written Assembler subroutines 
may yield unpredictable results. 

If the error was caused by an I/O 
operation, look up the Linkage Editor 
storage map to find the address of the DTP 



ixie xirsi: 
vjiU u£ T:;xic uxr tacie contains the address 



(.ciijjLc: J.V/J. die: 



of the corresponding CCB, For details on 
the CCB refer to the SRL publications 
describing the DOS/TOS Supervisor and I/O 
macro instructions. 

Data declared with the attribute 
EXTERNAL can be found using the addresses 
given in the Linkage Editor storage map. 

To determine the absolute address of 
static internal data refer to the offset 
table listing (see the section Offset 
2§^i2«lii§ting) . 

To locate the storage allocated to an 
automatic variable, the offset of the 
variable within the DSA (Dynamic Storage 
Area) is determined from the offset table^ 
and this offset is added to the DSA 
address of the block to which the variable 
is internal. The address of the DSA is 
automatically loaded into register 13 at 
prologue time. Word 20 of the DSA con- 
tains the DSA address of the statically 
embracing block. 

The load point of the main DSA is the 
next double-word boundary after the high- 
est high-core address of all external 
blocks linked in the program. 

More than one DSA may be allocated, 
i.e., if more than one block is active. 
To find the DSA of the block where the 
error is detected, check the byte pointed 
to by register 13. If this byte contains 
either X'hl' or X'h3' (b may be any hexa- 
decimal digit), register 13 points to the 
relevant DSA. In this case, the error 
message was most probably caused by a Pro- 
gram Check interrupt. 

The instruction that caused the inter- 
rupt can be found by means of the diag- 
nostic message. The old PSW and the regi- 
sters can be found at the location with 
the external label IJKZWSI, 
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If the byte contains X'05', register 13 
points to a LSSA (Library Standard Save 
Area), the second word of which contains 
the chain- back word. If this again points 
to a LSSA, repeat the chain-back process 
until the chain- back word points to a DSA- 
This DSA then belongs to the block where 
the error was detected. 

To identify the block, go to the chain- 
back address of the relevant DSA. If this 
points to another DSA, word 5 of the DSA 
contains the absolute address of the 
block. The block can then be identified 
using the object code listing and the Lin- 



kage Editor storage map. If the chain- 
back word does not point to a DSA, the 
relevant DSA is the DSA of the MAIN proce- 
dure ( see Figure 32), 

The chain of DSAs reseirbles the current 
environment at the point of execution 
where the error was detected. Each DSA in 
the chain has its corresponding currently 
active block. From where and at which 
location a specific block is activated can 
be determined by means of the DSA of the 
calling block. For detailed information 
on the first 20 words of the DSA refer to 
the section Linkage Conventions . 



MAIN.. PROCEDURE OPTIONS (MAIN),. 



CALL SUBl 

L 15,^(SUB1) 

BALR 14,15 



r- 



END,. 
L 

LM 
BR 



13,4(13) 

14,12,12(13) 

14 to STOP Routine 



DUMDSA 



Static Storage 



DSA SAVMAIN 



L_ 



i 



Flags 



AL3 (Block Description) 



Chain Bock 
A(DUMDSA) 



Chain Forward 
A(Next Available Core) 



Return Register 14 



Entry Register 15 



Work Area 



Variables 



.J 



^+t 






L. _ 






SUBl.. PROCEDURE,. 



USING *,15 

STM 14,12,12,(13) 



PROLOGUE 



CALL LAST 

L 15, =V (LAST) 

BALR 14,15 



RETURN 

L 13,4,(13) 

LM 14,12,12(13) 

BR 14 

Static Storage 



DSA SAVSUBl 



Flags AL3(Block Description) 



Chain Bock 
A(Calling DSA) 



Chain Forward 
A(Next Available Core) 



Return Register 14 



Entry Register 15 



Work Area 



Variables 



-I I 



+-• 



tt- 



LAST.. PROCEDURE,. 



USING M5 

STM 14,12,12(13) 



PROLOGUE 



RETURN 

L 13,4(13) 

LM 14,12,12(13) 

BR 14 



Static Storage 



DSA SAVLAST 



Flags AL3(Block Description) 



Chain Bock 
A(Calling DSA) 



Chain Forward 
A(Next Available Core) 



Return Register 14 



Entry Register 15 



Work Area 



Variables 

t 



. J 



Figure 32, DSA Chaining 
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Data Storage Requirements 



The storage requirements for data depend 
on the following two factors: 

1. The storage required for the data 
itself. 

2 , The storage required for the data 
descriptor. (The data descriptor is 
required whenever the compile- time 
data description is to be used in the 
object program.) 

Data Descriptors 



Data Iteins 



a riat-; 



dsscrxbe more than 



one data item. Only one data descriptor 
is required for a group of data items that 
have identical (either explicitly or 
implicitly declared) attributes, e.g. , for 
individual variables of identical attri- 
butes or for array elements. Thus, the 
statement 

DECLARE (A, B, C(21), D) FIXED DECIMAL 
(5,2), (E, F, G) PICTURE '$99.99'; 

requires only two descriptors : one 
describing A, B, the 21 C's, and D, and 
one describing E, F, and G. Constants 
(except those used in output lists), label 
variables, label constants, or pointer 
variables do not require a descriptor. 

A data descriptor and, therefore, 
storage in the object program is required 
only if the pertinent data item is used in 
a conversion or I/O library subroutine. 



r ' T 

I Fixed decimal 

1 Float decimal 

I Fixed binary J Coded 

I Float binary 

i Sterling 

I constants 



j. 

! Fixed decimal 
! Float decimal 
j sterling 



I- 

I Character 

jBit 

I Picture- 

I specified 

! character 



\- 

I Label 
^— 

I Pointer 

L 



Numeric 
(picture- 
specified) 



^ Arithmetic 



String 



^ 

Label 

Pointer 



Non- 
arithmetic 



.!._. ._ J-V-. - 



i igure j j SnOWs «,ne types or aata xteirs 
that require storage. In the following 
text, the storage requireirents for each of 
these items are specified and illustrated 
by means of examples. The storage 
requirements given in these examples per- 
tain to the data only. Unless otherwise 
stated, references to coded arithmetic and 
string data apply to both variables and 
constants. Other data types will have 
constants and variables explicitly dif- 
ferentiated in regard to storage 
requirements . 



CODED ARITHMETIC DATA 

Binary Fixed 

De f au It p r ec is ion: 15 bits 
Maximum precision: 31 bits 
Storage requirements : 

1 • Descriptor 

3 bytes (if required) 

2 . Data 

4 bytes internal fixed-point regard- 
less of declared or default precision. 
Scale factor roust_not be specified- 

Figure 34 shows the storage require- 
ments for the binary fixed data declared 
in the following sample statement: 

DECLARE 1(8,5), A FIXED BINARY (7), 
J STATIC, Z(3) FIXED BINARy(27); 



r T 

I DATA I DECLARED 

I ITEM I ATTRIBUTES 

j. _+ 

I I I Dimension (8,5) 

I I 

|. + 

I A I FIXED BINARY 
1^ I Precision (7) 

I J i STATIC 
I I 

I Z I Dimension (3) 
I I FIXED BINARY 
I I Precision (27) 

L X 



T T 1 

DEFAULT I 
ATTRIBUTES j BYTES 



FIXED BINARY | 160 
Precision (15) j 



None I H 

! 

FIXED BINARY i 4 
Precision (15) \ 

None i 12 



TOTAL 180 I 

J 



Figure 33. Types of Data Items 



Figure 34. Example of Binary Fixed Data 
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Deciinal_Fixed 

Default precision: (5,0) 
Maxinautn precision: (15»0) 
Storage requirements: 

1 . Descriptor 

3 bytes (if required) 

2 . Data 

Packed decimal form — 

4 bits = 1/2 byte for each digit. The 
sign is always stored and requires 1/2 
byte. The total storage required must 
be expressible in byte form, i.e., 
+5.2 requires 2 bytes (1/2 byte for 
the sign, 1 byte for the two digits, 
1/2 byte padding). 

Scale factor range: to 15 (if 
present) . 

Figure 35 shows the storage require- 
ments for the decimal fixed data declared 
in the following sample statement: 

DECLARE A FIXED, B(5,2, 3) FIXED, I FIXED 
STATIC, QFIXED(1U,2); 

r T ■ T r 1 

DATA I DECLARED j DEFAULT 

ITEM I ATTRIBUTES j ATTRIBUTES j BYTES 

A j FIXED j DECIMAL 

I j Precision ( 5» 0) 

B I Dimension j DECIMAL 

I (5,2,3) |Precision(5,0)| 90 
I FIXED I 



I f FIXED STATIC ) DECIMAL 

I I Precision (5,0) I 3 
l- 4 „ .-_,+ 4 

Q I FIXED I DECIMAL I 8 

I Precis ion (14, 2) | 
X . X 



TOTAL 



104 



Figure 35. Example of Decimal Fixed Data 

BinaryFloat 

Default precision: 21 bits 
Maximum precision: 53 bits 
Storage requirements: 

1. Descriptor 

2 bytes (if required) 

2 . Data 

Hexadecimal floating-point form (see 

the SRL publication IBM System/360, 

EliDciEl§§_of_0£eratign, Order No. 

A22-6821). 

a. Short floating-point form (U 

bytes) used for a precision of 

less than 22 bits. 
b- Long floating-point form (8 bytes) 

used for a precision of greater 

than 21 bits. 



Figure 3 6 shows the storage require- 
ments for the binary float data declared 
in the following sample statement: 

DECLARE A BINARY, B BINARY (29), C(2,5) 
BINARY (16), D FLOAT BINARY (50); 



r T 

DATA I DECLARED 
ITEM! ATTRIBUTES 



DEFAULT 
ATTRIBUTES 



I BINARY 1 FLOAT 1 4 

I 1 Precision (21) 

B j BINARY 1 FLOAT 

I Precision (29) 1 

C i Dimension ( 2, 5) j FLOAT 1 UO 
I BINARY \ 

I Precision (16) | 

D I BINARY FLOAT jNone 

I Precision (50) j 
X X. 



BYTES 



H 



1-- 

I TOTAL 60 I 

L J 

Figure 36. Example of Binary Float Data 

Decimal Float 

Default precision: 6 decimal digits 
Maximum precision: 16 deciracJ. digits 
Storage requirements: 

1. Descriptor 

2 bytes (if required) 

2. Data 

a. Short form (U bytes) used for less 
than 7 decimal digits - 

b. Long form (8 bytes) used for more 
than 6 decimal digits- 
Figure 37 shows the storage require- 
ments for the decimal float data declared 
in the following sample statement: 

DECLARE A (5, 3), B FLOAT (8), 
C DECIMAL (14), D; 



DATA 
ITEM 



DECLARED 
ATTRIBUTES 



-T T 1 

I DEFAULT 

1 ATTRIBUTES 1 BYTES 

+ ^ 



Dimension ( 5, 3) | DECIMAL FLOAT 
I Precision (6) 



FLOAT 1 DECIMAL 

Precision (8) i 



DECIMAL ! FLOAT 
Precision (14) | 

None I DECIMAL FLOAT 

I Precision (6) 

X 



60 



+- 



■i 



X ^ 

TOTAL 80 i 
J 



Figure 37. Example of Decimal Float Data 
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NUMERIC (PICTURE-SPECIFIED) DATA 

Default precision: not applicable 
Maximum length: after resolution of all 
replications, the picture-specified num- 
eric field must not be greater than 32 
characters. The number of possible 
picture-specified digit positions 

fixed (15 digits) or numeric float (16 
digits) , 
Storage requirements: 

1. Descriptor 

a. Fixed-point data — one byte for 
each picture character plus 8 to 
20 bytes, with an average of 12 
additional bytes (if required). 

b. Floating-point data -- one byte 
for each picture character plus 20 
to '<*''* bytes, with an average of 2h 
additional bytes (if required). 

c- Numeric sterling data — one byte 
for each picture character plus U 
bytes (if required). 

2 . Data 

One byte for eacn picture character 
except for M, V, K, and G. 

Figure 38 shows the storage require- 
ments for the numeric data declared in the 
following sample statement: 

DECLARE A PICTURE '$99.99\ B PICTURE 
' (8)9V(tt)9', C PICTURE •.99K+99', D 
PICTURE •ZZ99B9(2)B.9,99* ; 



DATA] 
ITEM 



BEFORE 
REPLICATION 
RESOLUTION 



AFTER 
REPLICATION 
RESOLUTION 



BYTES 



A 


-4 

1$99.99 


jsame 


\ 


6 


B 


-+ 

1 (8)9V(4)9 


+ 

I99999999V9999 


-+- 
1 


12 


C 


-+ ^- 

] .99K+99 


+ _ 

|Same 


4- 

1 


6 


D 


-+ 

1ZZ99B9(2)B. 

L 


9,99|ZZ99B9BB.9,99 


-+- 

1 
1 


13 






TOTAL 




37 



Figure 38. Example of Numeric Data 

STRING DATA 

Character-String Data 

Default precision: not applicable 
Minimum length: 1 cnaracter 
Maximum length: 255 characters 
Storage requirements: 

1 . Descr iQtor 

2 bytes (if required) 



2 . Data 

1 byte per character 

Figure 39 shows the storage require- 
ments for the character- string data de- 
clared in the following sample statement: 

DECLARE A (5) CHARACTER ( 20) , B CHARACTER 
r 1 -1 1 \ _ 
I xxa.7 } 

I DATA ITEM | DECLARED ATTRIBUTES \ BYTES i 

I A I Dimension (5) | 100 | 
I I CHARACTER (20) | | 
I- 1 + 1 

I B 1^ CHARACTER (111) | 111 | 
I- J. X ^ 

I TOTAL 211 I 

■ . J 

Figure 39. Example of Character-String 
Data 

Bit-String Data 

Default precision: not applicable 
Minimum length: 1 bit 
Maximum length: 64 bits 
Storage requirements : 

1 . Descriptor 

2 bytes (if required) 

2 , Data 

1 byte for each group of 8 bits or 
part thereof. Packed format is not 
permitted. 

Figure 40 shows the storage require- 
ments for the bit-string data declared in 
the following sample statement: 

DECLARE A BIT(12), B (11,7,2) BIT (1); 

r T ■ T 1 

I DATA ITEM | DECLARED ATTRIBUTES | BYTES \ 

j. + 4 ^ 

I A I BIT (12) I 2 j 
j. 4 4 ^ 

I B I Dimension (11,7,2) | 154 j 
I I BIT (1) II 

J, X X ^ 

I TOTAL 156 1 

L J 

Figure 40. Example of Bit- String Data 

Pictur e-S pecified Character- Str i ng Dat a 

Default precision: not applicable 
Minimum length: 1 character 
Maximum length: 255 characters 
Storage requirements : 

1 • Descriptor 

2 bytes (if required) 
2. Data 

1 byte per character 
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Figure 41 shows the storage require- 
ments for the picture-specified character- 
string data declared in the following 
sample statement: 

DECLARE A PICTURE 'dOS^X', B 
CHARACTER (105); 

r T T 1 

I DATA ITEM | DECLARED ATTRIBUTES | BYTES | 
j._ + + -__4 

I A I PICTURE M105)X' | 105 | 
|._ _+ f 4 

I B 1 CHARACTER (105) | 105 | 
^ _ X X 4 

I TOTAL 210 I 
L J 

Figure 41. Example of Both Character- 
String and Picture -Specified 
Character-String Data 

LABEL DATA 

Label Var iables 

Default precision: not applicable 
Maximum precision: not applicable 
Storage requirements: 8 bytes 

LabelConstants 

Default precision: not applicable 
Maximum precision: not applicable 
Storage requirements: 8 bytes for each 
occurrence of the label in an assignment 
statement or in a GO TO statement refer- 
ring to a label that is not contained in 
the block containing the GO TO statement. 
Label constants in R format items require 
U bytes. All other label constants do not 
require storage. 

Figure 12 shows the storage require- 
ments for the label data declared in the 
following sample statement: 

DECLARE A LABEL, B(7) LABEL; 

r T r 1 

I DATA ITEM | DECLARED ATTRIBUTES j BYTES | 
j. + + 4 

! A I LABEL I 8 j 
l- _ + ^ 4 

I B j Dimension (7) | 56 | 
I i LABEL I I 
1- X X 4 

I TOTAL 6U I 
L J 

Figure 42. Example of Label Data 

POINTER VARIABILIS 

Default precision: not applicable 
Maximum precision: not applicable 
Storage requirements: 4 bytes 



Figure 43 shows the storage require- 
ments for the pointer variable declared in 
the following sample statement: 

DECLARE P POINTER, A BASED (P) FLOAT; 

r T T T 1 

I DATA I DECLARED \ DEFAULT | | 

I ITEM I ATTRIBUTES | ATTRIBUTES | BYTES | 

I P I POINTER I None } 4 | 

|. X . X X 4 

I TOTAL 4 I 
L . . J 

Figure 43. Example of Pointer Data 

Data Storage Depending on Storage Class 

STATIC and AUTOMATIC data require the same 
amount of storage. No storage is required 
for BASED data. However, accessing based 
variables by means of pointers requires 4 
extra bytes per reference compared with 
the other storage classes. 



Storage of External Data 

Each distinct EXTERNAL variable, array, or 
structure requires storage in multiples of 
8 bytes, since padding to the next double- 
word boundary is required if the length of 
the EXTERNAL data item is not 8 or a mul- 
tiple of 8 bytes. Figure 44 shows the 
storage requirements of the EXTERNAL data 
declared in the following sample 
statement : 

DECLARE (A BIT (2), B( 3, .2, 3) CHARACTER ( 2) , 
C CHARACTER (9), D FLOAT (14),, E, 
F PICTURE '$99.99', G FIXED DECIMAL 
(13,2)) EXTERNAL; 



VARIABLE 



BYTE REQUIRED 

— T T — 

1 I 



^ 



DATA I 

STORAGE I PADDING | TOTAL 

A I 1 1 7 I 8 

B I 36 I 4 I 40 

C 1 9 I 7 I 16 

D I 8 I I 8 

E I 4 ! 4 




Figure 44. Example of External Data 
Storage 
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Use of Constants in The Source Text 

Constants may appear in the source text 
wherever an expression is permitted- In 
addition, they may appear as replication 
factors, upper bounds of a subscript range 
in the dimension attribute of an array, 
etc. Appearance and representation of 
constants in the object program depends 
entirely on their representation and con- 
text in the source program. Only the fol- 
lowing three cases are of concern to the 
programmer : 

1. If a constant appears in the source 
text as an argument in a function or 
subroutine procedure, its object-time 
representation is derived directly 
from the source-program representa- 
tion. For example, the statement 

CALL A (1.5, 3.7E-4, IIOOIIB) ; 

results in an object-time FIXED DECIM- 
AL representation of the constant 1.5, 
a FLOAT DECIMAL (short float) repre- 
sentation of the constant 3.7E-4, and 
a FIXED BINARY representation of the 
constant IIGOIIB. 

Note: If arguments are written as 
constants, these constants are trans- 
mitted to the called routine in coded 
form and with the precision derived 
from the source text representation. 
The called routine, in turn, assumes a 
certain internal representation of the 
argument as specified in the parameter 
declaration. The user must therefore 
ensure that base, scale, and precision 
of both arguments and parameters 
match* For instance, declaring the 
first parameter in the above example 
as FIXED (7,1) might lead to an 
object-time error because the called 
program assumes an argument that occu- 
pies U bytes, whereas the constant 1.5 
occupies only 2 bytes. 

2. If a constant appears in the source 
text as the upper bound of an array 
subscript, the appearance of this con- 
stant in the object program depends on 
how the expression used in this sub- 
script position is employed in the 
remainder of the source text. At 
best, no constant appears at object 
time for any upper bound. In the most 



unfavorable case, a FIXED BINARY con- 
stant appears in the object program 
for every upper bound in the dimensioi 
attribute of the DECLJ^>RE statement. 
Thus, 



nTrrr nop A fS 7 7 s R fQ 1 1 > ' 

may result in,- at most, five FIXED 
BINARY constants in the object pro- 
gram. At best, no object-time con- 
stant will appear for the five upper 
bounds in the source text. 

An object-time constant is derived 
from each source-text constant of a 
certain base, scale, and precision. 
However, base, scale, and precision of 
the object-time constant depend 
entirely on the context in which it is 
used. For example, the statements 

DECLARE A BINARY; 
A = 1.7; 

cause the constant 1. 7 to be stored in 
the object program in floating-point 
form, even though the source-text 
representation is fixed decimal. This 
shows that identically represented 
source-text constants may be converted 
at compile time into a number of dif- 
ferent object- time constants (this 
does not apply to constants in DO 
iteration specifications). For 
instance, the following sample 
statements 

DECLARE A FIXED DECIMAL, 

B BINARY, C FIXED BINARY; 
A = 2; 
B = 2; 
C = 2; 

result in three different object-time 
representations of the single compile- 
tiroe constant 2- On the other hand, 
constants of equal value, base, scale, 
and precision are stored only once in 
the object program unless NOOPT has 
been specified in the PL/I PROCESS 
card. When in doubt about constants 
which appear similar, e.g., 1.2E+7 as 
opposed to 12000000, the programmer 
should review the question of preci- 
sion of arithmetic constants in the 
Subset language publication. 
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Data Storage Mapping 



This section discusses the location of a 
variable in relation to other variables. 
The location of data with respect to the 
entire program is discussed in the section 

BoundarY^ Requi re ments 

In the object program, variables that are 
not part of a structure are grouped 
according to certain rules referred to as 
boundary requirements, which depend on the 
hardware configuration of the system used. 
For the System/360, the largest unit of 
storage is the "double word" (8 bytes) , 
which must always be on a double-word 
boundary (double-word aligned). That is, 
the first byte of any double word in 
storage must be on an address divisible by 
8. "Full words" Ci bytes) must be full- 
word aligned, i.e., the first byte of any 
full word in storage must be on an address 
divisible by 4. Bit strings, as another 
example, must be byte aligned, i.e., they 
may occur on any byte boundary. If any 
machine address divisible by 8 is chosen 
as arbitrary byte 0, the above boundary 
requirements can be reduced to the 
following: 

• double-word aligned data may appear on 
any byte 0; 

• full-word aligned data may appear on 
any byte 0, 4, 0, 4, etc.; and 

• byte-aligned data may appear on any 
byte 0, 1, 2, 3, ... 7, 0, etc. 



Storage Mapping — Element Data 

To minimize padding between element data 
items, the DOS/TOS PL/I compiler gathers - 
as far as possible - all element data 
items that are subject to the same boun- 
dary requirements. This is done regard- 
less of the point of declaration within 
the program. 

The following discusses the possibili- 
ties of mapping elementary data items not 
contained in structures or ar rays and 
should be understood as an introduction to 
the mapping of structures. 

Much storage can be saved by economic- 
ally arranging the individual data types. 
Consider the following example: 

A BIT(2), B, C BIT(9), D; 

The result of left-to- right storage 
allocation is illustrated in Figure 4 5. 



The total storage requirement in this 
example is 16 bytes, of which 5 are used 
for padding. 



12 34 567 1 23456 7 

Figure 45, Storage Allocation Example 1 

Rearranging the variables as follows: 

A BIT(2) , C BITO), B, D; 

results in a reduction of the total 
storage requirements to 12 bytes with only 
one padding byte. Figure 46 illustrates 
the storage allocation. 



I I 



Figure 46. Storage Allocation Example 2 

Finally, assume that the variables were 
rearranged as follows: 

B, D, A BIT(2), C BIT(9); 

This is the way in which the DOS/TOS PL/I 
compiler gathers elementary data items not 
contained in arrays or structures. The 
total storage requirements would be 
reduced to 11 bytes without any padding. 
The storage allocation is shown in Figiare 
47. 



T — r 



12345670 12 

Figure 47. Storage Allocation Example 3 

Storage Mapping ~ Arrays 

The storage requirement of an array equals 
the sum of the requirements of the indivi- 
dual data items contained in the array. 
Bit-string data items are aligned on byte 
boundary. Thus, the storage requirement 
of the array declared in the statement 

DECLARE A(5, 4,3) BIT(9); 

can be calculated as follows: The number 
of data items in the array is 5x4x3=60. 
Due to boundary alignment, each item 
requires 2 bytes. Total storage require- 
ment: 2x60=120 bytes. 



Data Storage Mapping 65 



The individual items of an array are 
stored in major row sequence. For the 
above example, this means that the items 
are stored as follows: 

A(l,l,l) 

r\ \ J_ • .I. y ^ J 

A ( 5 a 2 > 



Storage Mapping — Structures 

To minimize padding, the DOS/TOS PL/I com- 
piler gathers - as far as possible - all 
elementary data items that are subject to 
the same boundary requirements. 









^ jC _ 



Structure, sucn 
garnering or aaua is not perforrtied because 
a structure is regarded as one record, and 
the programmer might wish to predestine 
the relative position of every data item 
within that record, e.g., in a punched 
card. Thus, the statement below results 
in the storage allocation illustrated in 
Figure 48, The total storage requirement 
is 12 bytes, including 3 padding bytes. 

DECLARE 1 A ALIGNED, 2 B, 2 C BIT(l), 2 D; 



31 H, 

45 I, 
45 J, 
54 K, 
54 L; 



structure J has components at logical 
depth 5 although the level number is 54. 
The logical depth of these components is 
greater than that of the components of 
structure C (3), even though their level 
number (54) is not as high. 

When mapping a major structure, first 
map all minor structures at greatest log- 
ical depth n. Then continue with mapping 
the minor structures at logical depth n-1. 
The components that form the minor struc- 
ture at logical depth n-1 consist of: 

1, elementary items at logical depth n, 
and 

2. minor structures at logical depth n, 
which have already been mapped. 

After mapping the minor structures at 
logical depth n-1, proceed by mapping all 
minor structures at logical depth n-2. 
Again, the components that form the minor 
structure at logical depth n-2 consist of: 

1. elementary items at logical depth n-1, 
and 



Figure 48. Storage Allocation Example 4 

In this example, structure A, which has 
the unused 3 bytes between C and D, can be 
thought of as a record without any editing 
descriptors for the components B, C, and 
D. It should not be thought of as a bit 
string because this might lead the pro- 
grammer to erroneously assume that the 
first bit of the byte following C is the 
first bit of D. 

Logi cal _Degth Concept 

In the following discussion, the term 
"logical depth" is used to describe the 
level number of a minor structure or ele- 
mentary data item relative to the level of 
the major structure. A minor structure or 
elementary data item can have a high level 
number but be at a relatively low logical 
depth. For instance, in the following 
sample declaration: 

DECLARE 1 A, 

15 B, 
15 C, 

95 D, 

95 E, 
15 F, 

31 G, 



2, minor structures at logical depth n-1, 
which have already been mapped and 
contain the mapped structures at log- 
ical depth n. 

Continuing this process leads to the 
major structure, which is at logical 
depth 1. Mapping of the major structure 
is done by joining the coirponents at log- 
ical depth 2. These components consist 
of: 

1. elementary items logical depth 2, and 

2, minor structures at logical depth 2, 
which have already been mapped and 
contain the mapped structures at log- 
ical depth 3. These,, in turn; contain 
the mapped structures at logical depth 
4,, etc. 

The storage mapping of structures is 
done according to the set of rules listed 
below. In the mapping process, a com- 
ponent (or a group of partially mapped 
components) may be shifted to minimize the 
padding that may be required between the 
component and the component to be 
appended. The opportunity or potential 
for such shifting depends on the stringen- 
cy level of the element to be appended. 
The amount of shifting that is permissible 
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T r 

Alignment 
Requirement 



T 1 

Strin- 
gency 
Level 



Variable 
Type 

BIT(n)2 



DECIMAL FIXED 
(w, d) 

BINARY FIXED (w) 






CHARACTER (n) 



PICTURE 



BINARY FLOAT (w) 
w < 22 



DECIMAL FLOAT (w) 
w < 7 



LABEL 



POINTER 



Stored Internally 
as 



One byte for each 
group of 8 bits 
(or part thereof) 



One byte per 
character 



One byte for each 
PICTURE character 
except M,V,K,G 



Short 
floating point 



Storage 

Requirement^ 

(in Bytes) 



CEIL 



Number of 
PICTURE charac- 
ters other than 
M, V, K, and G 



Byte 



1/2 byte per | w+1 

digit plus 1/2 |CEIL 
byte for sign 

Binary integer 



Full-word 



Full-word 
(right- 
adjusted) 



Explanation 



Data may 
begin on 
any byte 



Data must 
begin on 
byte or 4 



Data must 
begin on 
byte or 4 



BINARY FLOAT (w) 
21 < w < 54 



DECIMAL FLOAT (w> 
6 < w < 17 



Long 

floating point 



Double- 
word 



Data must 
begin on 
byte 



-H 



^See Storage of External Data for data declared with attribute EXTERNAL. 
^Structures containing bit strings must have the attribute ALIGNED because the default 
attribute (UNALIGNED) is not permitted in the PL/I Subset language. 

L : 

Figure 49. Summary of Data Alignment Requirements and Stringency Levels 



is determined by the alignment require- 
ments of the element (s) to be shifted. 

Both the stringency level number and 
the alignment requirements for the indivi- 
dual data items are shown in Figure 49. 



Structure Mapping Rules 



Locate the first minor structure of 
the greatest logical depth. (See 
Figure 50, part A. The declaration 
shown is used throughout the figure. ) 

Begin the map with the first element 
of this minor structure. The map 
begins on byte zero (See Figure 5 0, 
part B) . 



Append the next element of the minor 
structure at the first following byte 
position where it may be legally 
placed. This byte position is deter- 
mined by the alignment requirement of 
the element to be appended. (See 
Figure 50, part B.) 



4. Owing to the alignment requirement, 

some unused space (padding) may result 
between the first and the appended 
element. The preceding element may 
then be shifted to the right provided 
the alignment requirement of that ele- 
ment is still satisfied after the 
shifting. If no shifting or only a 
partial shifting is permissible, the 
padding remains there permanently. 
(See Figure 50, part B.) 
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The elements so mapped are now per- 
manently joined and may be considered 
a single element. The alignment 
requirement of the joined items is 
that of the iteni of higher stringency 
level. 



Repeat rules 3 and U for all remainlna 
elements of the minor structure. 
Figure 50, part B.) 



(See 



7. Repeat rules 2 through 6 for all minor 
structures of the same logical depth. 
Map all minor structures individually. 
(See Figure 50, part C.) 

8. Repeat rules 2 through 7 for the minor 
structures of the next higher logical 
depth. Elementary items are appended 
according to rules 3 and 4. Minor 
structures are appended beginning at 
the byte position they had when they 
were previously mapped. Padding 
between the two elements, if any, is 
removed by 



shifting the succeeding element as 
far to the left as its alignment 
requirement permits, and 



b. shifting the preceding element as 
far to the right as its alignment 
requirement permits. 



9. 



Any padding that remains after these 
two shifting processes remains there 
permanently. (See Figure 50, part D. ) 



Continue this repetitive process until 
all minor structures are mapped, (See 
Figure 50, part E.) 



10. Map the major structure as if mapping 
a minor structure. (See Figure 50, 
part F.) 



11. If the shifted structure does not 
begin on byte zero, pad to the left 
until byte zero is reached. This is 
the physical beginning of the struc- 
ture. However, the name of the major 
structure still points to the first 
component of the structure . 



12. The first element of the structure 

must begin on byte zero of the struc- 
ture being mapped if the structure is 
a based variable and the pointer vari- 
able associated with it appears in the 
SET clause of a READ or LOCATE state- 
ment. In this case, the user must 
make sure that the structure begins on 
byte zero. Padding, if required, is 
best done with a dummy variable of the 
CHARACTER type. (See Figure 50, part 
G.) 



^ DECLARE 


1 A ALIGNED, 




2 B DECIMAL FIXED (11), 




2 C, 




3 D BIT (4), 




3E PICTURE '(8)97(4)9', 




3 F, 




4 G LABEL, 


Start here 


4 H PICTURE '9.9KS99', 
4 1, 




(Rule No. 


1) 5 K FLOAT (6), 




5 L BINARY (32), 




4 M, 




5 N CHARACTER (4), 




5 O FIXED (7,3), 




5 P FLOAT (16), 




2 Q, 




3 R BIT (7), 




3 S, 




4 T LABEL, 




4 U BINARY (20), 




4 V FLOAT (9), 




3 W CHARACTER (3) , 




2 X DECIMAL (6); 


Sample Declaration | 



® 



Rule No. 2 




Rule No. 3 



^=^ 



Rule No. 4 



J 


K 




L 




•f ¥ 

1 


; ! 


1 


1 i 1 
! ! ! 




.3 4 


5 6 


7 


2 3 4 


5 6 7, 



I Rule No. 6 
Application of Structure Mopping Rules Not. 2-6 



r^ 



Rule No. 2 



Rule 
No. 3 



1 2 3 4 5 6 



TfT ' ' ' I r I > 

) f I I • I I I I 

i '''••'■*' I, I 



16 7 1 2 3 4 5 6 7 

M 

Rule No. 6 

Application of Stnictura Mopping Rule No. 7 



Figure 50, Example of Structure Storage Mapping (Part 1 of 2) 
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Rule No. 6 



T — I — I — I — I — I — r 
I I I I I I I 

■ ■ I I I I L. 



12 3 4 5 6 7 
T U 



in 



T 1 r 

I I I 
J I L 



Rule No. 2 



Rule No. 3 



16 7 12 3 
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01234567 12 3 45 67 

Rule No. 6 
T+U V 



K 



T — I — I — I — I — I — r 
I I I I ■ I I 

J I I I I L—L. 



Rule No. 4 



45070 123 4 56 7 



4 5 1 2 3 4_67_0_1_67. 

Application of Structure AAopping Rule No. 8 
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Application of Structure Mapping Rule No. 10 



US 



T 1 r 

I I I 

J I L 



12123 4567 

If one of the conditions specified in Structure Mapping Rule 
No. 12 were applicable to structure A, the leading padding 
byte could be removed by inserting a dummy variable as 
follows; 

DECLARE 1 A ALIGNED, 



2 PADCHARACTER(l), | 
2 B DECIMAL FIXED (11), 
2 C, 



The unused character variable PAD now occupies byte so 
that the requirements of Rule No. 12 are met. 



Application of Structure Mapping Rule No. 12 



Figure 50. Example of Structure Storage Mapping (Part 2 of 2) 
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Subroutine Storage Requirements 



Three types of subroutines may be required 
in a program: 

1. Conversion subroutines. 

2. Subroutines called by built-in func- 
tion names, pseudo variables, and 
other implied subroutine calls. 

3. Subroutines called by I/O statements. 



Conversion Subroutines 

Conversion subroutines are required in « 
object program when certain conversions 
are implicitly requested in the source 
text. For example, the statements 



DECLARE A FIXED BINARY, 
BINARY; 

A = B + C; 



B FIXED, C 



imply that B is to be converted to binary 
float before being added to C, and that 
the sum is to be converted to fixed binary 
before being stored in A. 

The 18 conversion subroutines (see 
Appendix A) can perform every kind of data 
conversion permitted in the PL/I Subset 
language. Appendix B lists all possible 
combinations of data conversion and shows 
which subroutines are required to perform 
such conversions. For instance, the conv- 
ersion from numeric float to numeric fixed 
decimal requires subroutines U , 5, and 12. 
Subroutine 5 converts from numeric float 
to an internal intermediate form. Subrou- 
tine H converts from this internal inter- 
mediate form to coded fixed decimal. Sub- 
routine 12 converts from coded fixed 
decimal to numeric fixed decimal. 

Note: In some cases it may happen that no 
subroutine is used at object time although 
the condition for its inclusion was satis- 
fied. In these cases, the user has over- 
estimated his storage requirements. 

Average Conversion R eq uirements 

A system used for scientific purposes will 
normally use subroutines 1, 2, 7,8, 9, 
10, and possibly 17 and 18, with a total 
storage requirement of approximately 2K 
for an average program. 

A system used for commercial purposes 
will most likely use subroutines 11 and 12 
with a total storage requirement of appro- 
ximately .7k for an average program. 



Built-in Functions, Pseudo-Variables, And 
Other Implied Subroutine Calls 

Certain built-in functions and pseudo- 
variables require an object-time subrou- 
tine for proper functioning. Some of the 
built-in functions only allow float argu- 
ments. If an argument is not in this 
form, it is converted before the subrou- 
tine is activated. 

The source text operator ** is an 
implicit request for an exponentiation 
subroutine and, depending on the attri- 
butes of the aryuraents, six different sub- 
routines could be required. 

All information required for this type 
of subroutines is listed in Appendix C. 

Depending on the specific arguments, 
some functions that are marked IL may or 
may not require subroutines. For 
instance, a fixed first argument in the 
FIXED function would not require a subrou- 
tine, whereas a float first argument most 
probably would. However, the subroutine 
used is a conversion subroutine rather 
than a function subroutine. 

The object-time subroutines are cata- 
loged in the relocatable library. The 
programmer can find the module name in the 
entry-points column. If a module has more 
than one entry point, the module name is 
written first. 

Note: For some mathematical functions, 
the programmer may be interested in 
details such as error statistics and 
algorithms. For such details refer to the 
SRL publication IBM System / 360 Operati ng 
System, PL/I L ibrary Comp uta tional Sub rou- 
tines, Order No. GC28-6590. The DOS/TOS 
PL/I compiler uses the same algorithms as 
the OS PL/I compiler. Where applicable, 
the respective internal names of the OS 
PL/I compiler subroutines are given in 
parentheses in the rightmost column of 
Appendix C. 

Spec ial N ote R egarding Compa tibility 

Certain built-in functions available in 
the full PL/I language are not available 
in the PI/ 1 Subset language.. Thus, if the 
name of a user-written function procedure 
happens to be the same as that of an 
unavailable built-in function, the user- 
written function procedure is called if 
the program was compiled by means of the 
DOS/TOS PL/I compiler because the built-in 
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function of that name is not available. 
However, if this program were compiled by 
means of the OS PL/I compiler, the built- 
in function of that name — which, in this 
case, is available — would be called. 
For example: 

A : PROCEDURE ; 



X = REAL(Y) ; 



END; 

REAL is a function procedure. If this 
procedure is compiled by means of the OS 
PL/I compiler, the built-in function REAL 



is called. Therefore, user- written func- 
tion procedures should be named in such a 
manner as to avoid these complications. 



Subroutines Called by I/O Statements 

Subroutines may be called by I/O source 
statements for use at object time. The 
library subroutines that may be called are 
listed and described in Appendix D. 

Care should be taken that any subrou- 
tine called by an I/O statement does not 
itself contain an I/O statement, a PUT/GET 
STRING statement, or invoke another sub- 
routine containing such a statement. 
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I/O Storage Requirements 



This section provides the information that 
allows the user to determine the amount of 
storage required for I/O purposes at 
object time. Object-time core storage is 
required 

1. as a function of the file declaration 
itself, and 

2. by library subroutines called by I/O 
statements, such as GET, PUT, etc. 

The library subroutines called by I/O 
statements are listed in Appendix D. 



File Declarations 

Each file declaration requires four items: 

1. Buffers (if required) 

2 i DTF table 

3 . Appendage 

U, IOCS logic module 

The first three items are unique to 
each declaration. The fourth may be used 
by various file declarations. 

BUFFERS 

The number of buffers and the correspond- 
ing storage requirements directly derive 
from the file declaration. 

For files other than REGIONAL or INDE- 
XED, the buffer size is equal to the block 
size specified in the F, V, or U option. 
Thus, 80 bytes are required with the 
option F(80). If, in addition, the option 
BUFFERS (2) is used, the storage require- 
ments for the buffers of this file are 
doubled. The total storage required for 
such files equals the sum of the storage 
requirements for all buffers used for all 
these files. 

Note: No buffer storage is required if 
the F or U option is used with unbuffered 
files. 

Additional buffer storage (8 ♦ number 
of extents) is set aside for REGIONAL 
files. 

For REGIONAL (3) files the key length 
must be added to the buffer length. 

The buffer storage requirements for 
indexed files can be calculated according 
to the following formulas: 



1 • ^?§§j5gj_§ggij^"^^§l ■J:?£^^.^Q'3 update 

unblocked: recsi2S-!-2* keylength+10 
blocked: MAX(blocksize,keylength+10+ 
recs ize) 

2 . Indexed sequential output 

blocksize+keylength+8 +recsize 
[+keylength if unblocked] 

3 • Indexed dir ect update 

recsizs [Tkeylength if unblocked] 
[+ADDBUFF if specified] 
[+MAX ( S+keylength+blocksize, 
8+keylength+lO+recsize) if ADDBUFF 
not specified] 
[+INDEXAREA if specified] 

^ • Indexed direct input 

keylength+MAX (bloGksize,10+recs ize) 
[+INDEXAREA if specified] 



DTF TABLE 

The DTF (Define The File) table is 
required for each declaration. The func- 
tion of the DTF table is (together with 
the appendage) to allow communication 
between the object prograir produced froit; 
I/O source statements and the DTF program. 
The DTF program in turn comirunicates with 
the operating system for physical device 
control. 

The DTF table has a fixed length for 
each I/O device type. Figure 51 shows the 
storage requirements for the individual 
DTF tables. 

The number of DTF tables is equal to 
the number of files. The total storage 
required for all DTF tables is, therefore, 
equal to the sum of their individual 
storage requirements. Thus, an object 
program using three printers and five buf- 
fered, blocked- record, magnetic tape files 
would require 

3 X 48 + 5 X 112 = 704 bytes of storage 

for DTF tables. 

A DTFCD table is generated for each 
card device. Figure 52 shows the PL/I 
attributes and the corresponding DTFCD 
parameters . 
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Figure 51. Storage Requirements for DTF 
Tables 



A DTFPR table is generated for each 
printer. Figure 53 shows the PL/I attri- 
butes and the corresponding DTFPR 
parameters. 

A DTFMT table is generated for each 
magnetic tape drive. Figure 54 shows the 
PL/I attributes and the corresponding 
DTFMT parameters. 

A DTFSD table is generated for each 
disk file with the CONSECUTIVE option. 
Figure 55 shows the PL/I attributes and 
the corresponding DTFSD parameters. 



PL/ I ATTRIBUTES 



T 1 

DTFCD PARAMETERS 



Blocksize in F option 



Logical device address 
in MEDIUM option 



Dev. type in MEDIUM opt. 
2540 
1442 
2520 
2501 



Function attribute 
INPUT 

OUTPUT 



F (blocksize) 



BUFFERS option 
BUFFERS (1) 
BUFFERS (2) 



2540, OUTPUT 



Control character for 
RECORD I/C 

CTLASA 

CTL360 



BLKSIZE 



DEVADDR 



DEVICE=2540 
DEVICE=14 42 
DEVICE=2520 
DEVICE=2501 



TYPEFILE=INPUT 
ECFADDR 

TYPEFLE=OUTPUT 
SSELECT=2 



RECFORM=FIXUNB 



ICAREAl 
lOAREAl 
I0AREA2 
I0REG=(2) 



CRDERR=RETRY 



CTLCHR=ASA 
CTLCHR=YES 



Figure 52, PL/I Attributes and Corres- 
ponding DTFCD Parameters 



PL/ I ATTRIBUTES 



T n 

DTFPR PARAMETERS 



Blocksize in" F option 



Logical device address 
in MEDIUM option 



Dev. type in MEDIUM opt. 
1403 
1404 
1443 
1445 



-+- 



F (blocksize) 



BUFFERS Option 
BUFFERS (1) 
BUFFERS (2) 



USAGE attribute 

STREAM 

RECORD 
CTLASA 
CTL360 



BLKSIZE 



DEVADDR 



DEVICE=1403 
DEVICE=1404 
DEVICE=1443 
DEVICE=1445 



RECFORM=FIXUNB 



lOAREAl 
lOAREAl 
ICAREA2 
I0REG=(2) 



-i 



CTLCHR=ASA 
PRINTOV=YES 
CTLCHR=ASA 
I CTLCHR=YES 



Figure 53. PL/I Attributes and Corres- 
ponding DTFPR Parameters 
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PL/I ?kTTRIBUTES 



■T 1 r 

jDTFMt PARAMETERS! |PL/I ATTRIBUTES 
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{Blocksize in F, 
! V, U option 



1 BLKSIZE 



I- _+__ 

iRecsize in F option |RECSIZE 



!.__-_ _ +-i~:— 

I Logical device address iDiiVAUUK 

I in MEDIUM option j" 

J. _„„ 1__ 

IF. V- U option ! 



F (blocksize) 
F (blocksize, 
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V (maxblocksize) 

U (maxblocksize) 
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Figure 5U. PL/I Attributes and Corres- 
ponding DTFMT Parameters 

A DTFDA table is generated for each 
disk file with the REGIONAL option. 
Figure 56 shows the PL/I attributes and 
the corresponding DTFDA parameters. 
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Figure 55. PL/I Attributes and Corres- 
ponding DTFSD Parameters 



DTF APPENDAGE 

The DTF appendage, like the DTF table, 
consists of information derived from the 
file declaration. It also allows communi- 
cation between the object program produced 
from I/O source statements and the DTF 
program. The length of the appendage is 
exclusively determined by the presence of 
a single attribute or option. If the 
declaration 



contains the INDEXED option, the 
appendage length is UO bytes; 
contains the REGIONAL option, the 
appendage length is 56 bytes; 
contains the BOFFERED, STREAM, or UPD- 
ATE attribute, the appendage length is 
Iti bytes; 

contains the PRINT attribute or is for 
SYSLST, the appendage length is 32 
bytes ; 

does not apply to one of the file 
types listed under items 1 through 4, 
the appendage length is 16 bytes. 



The number of appendages is equal to 
the number of files. The total storage 
required for appendages is equal to the 
sum of their individual storage 
requirements. 



PL/I ATTRIBUTES 
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Blocksize in F option 



Device type in 
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F (blocksize) 
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Figure 56. PL/I Attributes and Corres- 



PL/I 

ATTRIBUTES 



INPUT 
SEQUENTIAL or 



INPUT DIRECT 



OUTPUT 
SEQUENTIAL 



UPDATE DIRECT 



Device type 



VERIFY or 
device 
type = 2321 



F(a) 
F(a,b) 



KEYLENGTH 
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INDEXMULTIPLE 

EXTENTNUMBER 

KEYLOC 

INDEX ARE A 



ADDBUFF 
HIGHINDEX 2311 



DTFIS PARAMETERS 



TYPEFLE=SEQNTL 
I CARE AS 
I0REG=(2) 
ICROUT=RETRVE 
KEYARG^ 



TYPEFLE=RANDOM 
lOAREAR 
ICREG=(2) 
IOROUT=RETRVE 
KEYARG (separate) 



lOAREAL 

WORKL (only if blocked) 

IOROUT=LCAD 



TYPEFLE=RANDOM 

lOAREALS,** 

WORKL** 

I CA REAR 2 

I0REG=(2) 

IOROUT=ADDRTR 

KEYARG^, 3 
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VERIFY=YES 



4- 



RECFORM=FIXUNB 
RECFORM=FIXELK 
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RECSIZE 



KEYLEN 
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lOSIZE 

HINDEX=n 



2314 
2321^ 
f 



ponding DTFDA Parameters 



^ Separate for blocked 

2 ICAREAL and lOAREAR rray be one and the 
same area 

3 Same as WORKL if unblocked 
** ADD separate 



Figure 57. PL/I Attributes and Corres- 
ponding DTFIS Parameters 

A DTFIS table is generated for each 
disk file with the INDEXED option. Figure 
57 shows the PL/I attributes and the 
corresponding DTFIS parameters. 
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A DTFDI table is generated for Stream 
files or buffered Record files if 

1, the logical address specifies SYSIPT, 
3YSLST, or SYSPGii in the MEDIUM 
option, 

2 , records are of fixed length and 
unblocked, and the record size Cn) is 

not greater than 80 for SYSIPT 
not greater than 81 for SYSPCH 
not greater than 121 for SYSLST and 

3, for output files either 

CTLASA (RECORD OUTPUT files) or 
PRINT (STREAM OUTPUT files) 

is si^ecified. 

Figure 58 shows the PL/I attributes and 
the corresponding DTFDI parameters. 
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Figure 58. PL/I Attributes and Corres- 
ponding DTFDI Parameters 



required for each module is stated in 
bytes. 

r T T _=_^====j 

I Card I One Buffer | Two Buffers | 
I }. ^ + _ .,_ ^ 

I Files j Input | Output! Input | output | 

i 25h0 j 96 i 192 I 128 | 216 | 

! 1442 j 100 I 74 i 132 \ 116 j 

! 2520 i 96 I 80 j 128 \ 124 i 

I 2501 I 96 I ~ I 128 I — I 

L . .i. JL X X J 

Figure 59. IOCS Logic Modules for Card 
Reading and Punching Devices 
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Figure 60. IOCS Logic Modules for 
Printers 



^ I 



T 1 

I Unbuffered I 



H 



r T •"- 

I Buffered 
I j. ^ ^.. 

[Tape Files! F j U ! V ! | 

j Backwards | 738 j 556 | — j j 

|. 4. 4. ^ ^ 318 I 

JAll Others! 690 | 564 | 762 | j 

L X X X X J 

Figure 61. IOCS Logic Modules for Magnet- 
ic Tape Units 



IOCS LOGIC MODULE 

The IOCS logic module uses the information 
obtained from the DTF table and the appen- 
dage, to communicate between the object 
program and the DOS/TOS control program. 
Different IOCS logic mpdules are used 
depending on the options and attributes 
specified in the file declaration. Files 
having the same options and attributes use 
the same IOCS logic module. For instance, 
any number of file declarations, each of 
which refers to a double-buffered input 
file using a 2540 card reader, would gen- 
erate a requirement for one single IOCS 
logic module only. 

The device type is the principal factor 
in determining which IOCS logic module is 
to be used. In Figures 59 through 64, the 
individual modules are therefore grouped 
according to device types. The storage 



If both BACKWARDS and non- BACKWARDS 
modules are used in the same program, only 
the BACKWARDS module is included. 

r T ^ T 1 

\ I Consecutive {Regional ! 

I Disk l- T -I- T ^ 

{Files !Un- I I i ! 

{ {buffered { Buffered { { { 
I ( |. ^ ^ ^ I I 

I I (F|V{U{1!3( 

^ + : + + + 4___.+ 4 

llnput { 682 { 546{ 746| 618{ 392! 392{ 
|._- 4__ ^ 4 ^ + 4 ^ 

{Output! 682 ! 574{1166{ 730{ 392! 696| 

lUpdate! 722 { 910{ 1255{ 1062( 392{ 696! 
i. X X X ._x X X j 

Figure 62. IOCS Logic Modules for Disk 
Units (other than INDEXED 
Files) 
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r T T — r ^ 

I Disk I Input I Output I Update \ 
i I I j. ^ ^ 

I Indexed Files | | | Bio eked | Unbl . | 

I Sequential | 1086 1 803 | 1086 |1086 | 

I Direct I 9901 -- | 2948 | 2752 | 

I with INDEXAREAJ 1138 j — | 3162 |2966 j 

I with ADDBUFF I — I ~ I 3220 | 2936 | 

L . J. J. X X J 

Figure 63. IOCS Logic Modules for Disk 
Units (INDEXED Files) 

r T 1 

I I BUFFERS ( 1) BUFFERS ( 2 ) 

|. + ^ 

! Input I 308 368 j 

i Output I 643 723 I 

L i J 

Figure 64. IOCS Logic Module for DTFDI 
Files 



EXAMPLES 

The following examples show the storage 
requirements for buffers, DTF table, 
appendage, and IOCS logic module. 

Exanj2le_l 

DECLARE PUNCHF FILE OUTPOT ENVIRONMENT 
(F(80) MEDIUM (SYSPCH, 2540)); 



Buffers 

DTF table 

Appendage 

IOCS logic module 

Total 

Exam2le_2 



80 bytes 
136 bytes 

24 bytes 
192 bytes 

432 bytes 



DECLARE PRINTF FILE STREAM OUTPUT PRINT 
ENVIRONMENT (CONSECUTIVE F(121) BUFFERS 
(1) MEDIUM (SYSLST, 2400)); 



Buffers 

DTF table 

Appendage 

IOCS logic module 

Total 

Examele_3 



121 bytes 

240 bytes 

32 bytes 

690 bytes 

1083 bytes 



DECLARE TAPEFF FILE RECORD UNBUFFERED 
ENVIRONMENT (U(512) MEDIUM (SYS004, 2400) 
LEAVE NOLABEL); 



Buffers 

DTF table 

Appendage 

IOCS logic module 

Total 



bytes 

4 8 bytes 

16 bytes 

318 bytes 

382 bytes 



Exaniple 4 



DECLARE TAPEBF FILE RECORD BACKWARDS 
UNBUFFERED ENVIRONMENT (U(512) MEDIUM 
(SYS004, 2400) LEAVE NOLABEL); 



Buffers 

DTF table 

Appendage 

IOCS logic module 

Total 



bytes 

4 8 bytes 

16 bytes 

318 bytes 

38 2 bytes 



j lx§S!2i§_5 

DECLARE DISKIF FILE STREAM INPUT ENVIRON- 
MENT (F(1739) BUFFERS (2) MEDIUM (SYSOOl, 
2311)) ; 



Buffers 

DTF table 

Appendage 

IOCS logic module 

Total 

Example 6 



347 8 bytes 

136 bytes 

24 bytes 

546 bytes 

418 4 bytes 



DECLARE DSKF FILE RECORD UPDATE BUFFERED 
ENVIRONMENT (F(1024, 256) BUFFERS (1) 
MEDIUM (SYS002, 2311)); 



Buffers 

DTF table 

Appendage 

IOCS logic module 

Total 

Example 7 



1024 bytes 

160 bytes 

24 bytes 

910 bytes 

2118 bytes 



DECLARE DSKR3F FILE RECORD OUTPUT DIRECT 
KEYED ENVIRONMENT (REGIONAL (3) F(800) 
MEDIUM (SYS003, 2311) KEYIENGTH (9)) 

Buffers 809 bytes 

8x3 extents (default) 24 bytes 



DTF table 
Appendage 
IOCS logic module 

Total 

Example 8 



28 8 bytes 

56 bytes 

696 bytes 

187 3 bytes 



DECLARE DSKRIF FILE RECORD UPDATE DIRECT 
KEYED ENVIRONMENT (REGIONAL (1) F(600) 
MEDIUM (SYS004, 2311)); 

Buffers 600 bytes 

8x3 extents (default) 24 bytes 
DTF table 216 bytes 

Appendage 56 bytes 

IOCS logic module 392 bytes 



Total 



1288 bytes 
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Exa[n2le_9 

DECLARE TAPERF FILE RECORD INPUT BUFFERED 
ENVIRONMENT (V(20U8) BUFFERS (2) MEDIUM 
(3Y3005, 2h00)); 



Buffers 

DTF table 

Appendage 

IOCS logic module 



4096 bytes 

128 bytes 

2fi bytes 

762 bytes 

5010 bytes 



Exa[n2le_10£ 

DECLARE INDSQI FILE RECORD INPUT KEYED 
ENVIRONMENT ( F(800,80) MEDIUM (SYSOll, 
2314) INDEXED KEYLENGTH(IO) EXTENTNUMBER ( 
3) INDEXMULTIPLE KEYL0C(15) ) ; 



Buffers 

DTF table 

Appendage 

IOCS logic module 

Total 



296 bytes 

40 bytes 

1086 bytes 

2222 bytes 



DECLARE INDDUP FILE RECORD UPDATE DIRECT 
KEYED ENVIRONMENT (F (800,80) MEDIUM 
(SYS012,2321) INDEXED KEYLENGTH(12) VERIFY 
EXTENTNUMBER (2) OFLTRACKSO) KEYLCC(23) 
ADDBUFF(1688)); 



N ot e; If all of the file declarations 
shown in these examples were to appear in 
the same program, the total storage 
requirements would be less than the sum of 
the individual storage requirements 
because, in a few cases, different file 
declarations would use the same IOCS logic 
module. 



System Units 



SYSPRINT 

The storage required for the DTF table, 
appendage* and IOCS logic module for SYS- 
PRINT is 416 bytes for TOS and 424 bytes 
for DOS. If DOS allows a 2311 as SYSLST, 
688 bytes are required. 



SYSIN 

The storage required for the DTF table, 
appendage, and IOCS logic module is 192 
bytes for TCS and 216 bytes for DOS. If 
DOS allows a 2311 as SYSIPT, 408 bytes are 
required. 



Buffers 
DTF table 
Appendage 
j.'vjv,t> j.ogx< 

Total 



ll!U\_iUXC 



1768 bytes 

576 bytes 

40 bytes 

3 220 bytes 

5604 bytes 



Note: If SYSIN and SYSPRINT are used in 
one program, the storage required for both 
is 568 bytes for TOS and 600 for DOS. The 
storage requirement is 920 bytes for DOS 
if a 2311, 2314, or 2319 is permitted for 
SYSIPT or SYSLST. 
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Program Overhead 



object -prog ram overhead derives from the 
following two sources: 

1. The DOS/TOS Supervisor, the size of 
which is installation-dependent. 

2. The general PL/I overhead area, which 
exists as a function of the PL/I 
source text. This area comprises the 
following four parts: 

a. The static storage area, 

b. The dynamic storage area. 

c. The block prologue. 

d. The PL/I control module. 



Static Storage Area 

static storage is required by the seven 
items listed below. (Note that internal 
blocks require only the static storage 
listed under items 5-7.) 

1. A constant basis of 132 bytes. 

2. All variables in any block declared 
with the attribute STATIC. 

3. Constants used in the source text, 

U. Four bytes for 

a. each library subroutine explicitly 
or implicitly used in the source 
text; 

b. each reference to a procedure that 
is external to the procedure under 
construction; and 

c. each distinct data item contained 
in any block and declared with the 
attribute EXTERNAL. 

5. A communications area of 4 bytes. 

6. An entry table with a minimum length 
of 4 bytes. If the block is a proce- 
dure, an additional entry of U bytes 
is made for each ENTRY statement in 
the block. 

7 . An entry of 8 bytes is made for the 
occurrence of each different condition 
in any ON statement internal to the 
block. 

Since items 1, 5, and 6 are always 
required, the minimum static storage area 
required is 140 bytes j even for the most 
trivial procedure. For example, 

A: PROCEDURE OPTIONS (MAIN); 
END; 



Examples of Calculating Static S torage 
Requirements 

The following procedure: 

A: PROCEDURE OPTIONS (MAIN) ; 

DECLARE B FIXED BINARY STATIC; 
C : PROCEDURE ; 

D : ENTRY ; 

RETURN ; 

END; 
E: BEGIN; 

DECLARE I STATIC; 

I=1101B; 

END; 

F: ENTRY; 
END; 

consists of the blocks A, C, and E. The 
static storage requirements of the indivi- 
dual blocks are discussed in terms of the 
items 1 through 7 listed above. 



Block_A 

1. 132-byte basis 



132 bytes 



2. 



Two variables with the STATIC 
attribute 



8 bytes 

3. One constant U bytes 

4. Communications area 4 bytes 

5. Entry table of 4 bytes minimum 

plus 4 bytes for entry point F 8 bytes 

TOTAL 156 bytes 
Block _C 

1. Communications area 4 bytes 

2. Entry table 8 bytes 

TCTAL 12 bytes 
Block_E 

1. Communications area 4 bytes 

2, Entry table 4 bytes 

TOTAL 8 bytes 

Consider another external procedure A 
that contains no other blocks. It uses 
4 00 bytes of static data storage 
(variables and constants) . It requires 
five library subroutines explicitly and 
three library subroutines implicitly. 
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Three procedures external to A are 
referred to in procedure A. Six variables 
are declared with the attribute EXTERNAL. 
The procedure has seven secondary entry 
points and contains six OS statements, of 
which four have differing conditions. 
External procedure A would require the 
following static storage: 



1. 132-byte basis 

2 . STATIC variables 

3. Constants 



132 bytes 



400 bytes 



4. a. 8 library subroutines 32 bytes 

b. 3 procedures external to A 12 bytes 

c. 6 EXTERNAL variables 24 bytes 



5. Communications area 

6 . Entry table 

7. Four ON statements with 
differing conditions 



3 2 bytes 



32 bytes 



TOTAL 668 bytes 

Finally, consider a third external pro- 
cedure W that contains two other proce- 
dures, X and Y. Procedure Y contains a 

BEGIN block Z. 

W uses 400 bytes of static data 
storage, X and Y each use 100, and Z uses 
200 bytes. Procedure W requires 3 library 
subroutines, X requires 2, Y requires 5, 
and Z requires 13. The library subrou- 
tines used in blocks W, X, and Y are ail 
different. The 13 subroutines used by Z 
comprise 3 that are required by other 
blocks. No procedure external to W is 
referred to, and there is no EXTERNAL 
data. Procedure W has 5 ENTRY statements, 
X has 2, and Y has 3. There are no ON 
statements in W, 2 ON statements with 
identical conditions in X, 3 ON statements 
with differing conditions in Y, and no ON 
statement in Z. 

The static storage requirements for the 
individual blocks are as follows: 



Blgck_W 

1 ~"-| OO- 

2. STATIC variables 

3. Constants 

4. A total of 2 library 
subroutines 



132 bytes 

800 bytes 

80 bytes 



5. Communications area 4 bytes 

6. Entry table 24 bytes 

TOTAL 1040 bytes 



Block_X 

1, Communications area 

2, Entry table 

3, One ON statement 



4 bytes 

12 bytes 

8 bytes 



TOTAL 24 bytes 
Block_Y 

1. Communications area 4 bytes 

2. Entry table 16 bytes 

3. Three differing ON conditions 24 bytes 

TOTAL 44 bytes 






1 . Communications area 

2. Entry table 



TOTAL 



4 bytes 
4 bytes 
8 bvtes 



The total static storage required by 
external procedure W thus amounts to 

1040 + 24 + 44 + 8 = 1116 bytes. 



Dynamic Storage Area 

Each blocks has its own dynamic storage 
area. The dynamic storage area is zero 
when the block is not active. The length 
of the dynamic storage area when the block 
is active is determined by the following 
five items: 

1. Data with the attribute AUTOMATIC, 
either declared or by default. 

2. A communications area of 80 bytes. 

3. Four bytes for each differen t paramet- 
er to be transmitted to this block. 

4. Working storage area I: 

This area is used to store intermedi- 
ate results of arithmetic expressions. 
The length of this area is a function 
of the complexity of the source text. 
For a program with arithmetic data 
only, the average length of this area 
is approximately 36 bytes. However, 
if the expressions contain character 
strings, the length increases with the 
length of the character strings. 

5. Working storage area II: 

This area is used to store expressions 
contained in DO loops. DO statements 
may be of either one of the following 
three forms: 



O f\ 
O vj 



a. DO var=expr-l,expr-2, . , ., expr-n; 
For such DO statements, the expre- 
ssions are developed and stored 
directly in the variable so that 
no additional storage is required. 

b. DO var=expr-l TO expr-2; or 
DO variable=expr-l BY expr-2; 

16 bytes are required for each DO 
statement of this form, regardless 
of the number of iteration speci- 
fications in each statement. 

TO BY 

c. DO var=expr^l expr-2 expr-3; 

BY TO 

2U bytes are required for each DO 
statement of this form, regardless 
of the number of iteration speci- 
fications in each statement. 

The information required to determine 
which iteration specification is being 
operated upon is also stored in work- 
ing storage area II. Each DO state- 
ment with more than one iteration spe- 
cification requires additional bytes 
to service all iteration specifica- 
tions. Thus, each DO statement 
requires zero, 16, or 2U bytes for 
storing expressions within iteration 
specifications, plus 8 bytes if there 
is more than one iteration specifica- 
tion for the DO statement. 



E:<:a[nple of Calculating Dynamic Storage 
Requirements 

Assume a procedure consists of the extern- 
al procedure A, which contains the intern- 
al procedures B and C. Internal procedure 
C contains the BEGIN block D. A and B 
each have 400 bytes of AUTOMATIC data, C 
has 200, and D has 100 bytes of AUTOMATIC 
data. Procedures A, B, and C have only 
one entry point (their primary entry 
point), and each procedure has a list of 
five parameters. Only coded arithmetic 
data is used. The dynamic storage 
requirements of the individual blocks are 
then as follows: 



Blgck_A 

1 . Data 

2 . Communications area 

3. Parameter storage 

'i . Working storage area I, 



400 bytes 

80 bytes 

20 bytes 

36 bytes 



5. Working storage area II (de- 96 bytes 
pends on complexity of DO* s) 



Block B 

1. Data 

2. Communications area 

3. Parameter storage 

4. Working storage area I, 
approx. 



4 00 bytes 

80 bytes 

20 bytes 

36 bytes 



5. Working storage area II, 
approx. 



Block C 

1. Data 

2. Communications area 

3. Parameter storage 



4. Working storage area I, 
approx. 



32 bytes 
TOTAL 568 bytes 

200 bytes 

80 bytes 

20 bytes 

36 bytes 



Block_D 

1, Data 

2. Communications area 



3. Working storage area I, 
approx. 

4. Working storage area II, 
approx. 



TOTAL 336 bytes 



100 bytes 
80 bytes 
36 bytes 



32 bytes 



TOTAL 632 bytes 



TOTAL 248 bytes 

The total requirement for dynamic 
storage at a given moment depends on which 
blocks are simultaneously active. The 
total storage required is the sum of the 
dynamic storage areas for the active 
blocks. In the above example, this is a 
minimum of 632 bytes. If all blocks are 
active simultaneously, the dynamic storage 
requirements amount to 1784 bytes. 



The Block Prologue 

The prologue is a set of instructions 
generated for a PROCEDURE, ENTRY, or BEGIN- 
statement. The generated instructions 
vary depending on the statement. The 
minimum prologue is 52 bytes. The maximum 
is approximately 140 bytes. The minimum 
prologue is used whenever the block is a 
BEGIN block. In all other cases, the 
average is approximately 60 bytes per pro- 
logue. A secondary entry point with 12 
arguments results in the maximum of 140 
bytes - 
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The PL/I Control Routine 

The PL/I control routine is a library sub- 
routine, which is always required in 
storage for PL/I programs. It is respons- 
ible for the interaction of the individual 
PL/I program components. Some of its 
functions are listed below: 



1. Dynamic storage allocation. 

2. Hardware interrupt servicing. 

3. Handling of ON conditions. 

U. Conscructing diagnostic messages. 

5. Terminating execution. 



Transmitting communications informa= 
tion from block to block. 

Providing library work soace. 



The PL/I control routine is fixed in 
length (approximately 1500 bytes) and is 
present orily once in a PL/I program, 
regardless of the complexity of blocking 
structures, the number of external proce- 
dures, and depth of overlaying. 

Note: In the discussion of the program 
overhead, it was shown where the STATIC 
and AUTOMATIC data will be. In all furth- 
er references, the term "overhead" is used 
for the actual overhead without data and 
without the DCS/TOS control program. 
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Source Text And Object Program 



After having estimated the storage 
requirements of (1) data, (2) library sub- 
routines, (3) file declarations, and (4) 
overhead contained in the program, the 
user can determine what part of the total 
storage capacity is left for the remaining 
part of the program. The remaining part 
mainly consists of (1) in-line instruc- 
tions produced directly from the source 
text and (2) calling sequences to subrou- 
tines for those operations that cannot be 
done in line. 

What instructions are produced from the 
source text can be shown by a simple 
example. 

DECLARE A FIXED DECIMAL; 



ssions within an iteration specification, 
the number of options chosen, and the 
number of iteration specifications. 
However, the following average values can 
be assumed: 

1. In a purely scientific environment, 
the average PL/I source statement 
generates ten 4- byte instructions. 

2. In a purely commercial environment, 
the average PL/I source statement 
generates seven 4-byte instructions. 

3. These average values are considerably 
increased by an excessive use of con- 
versions of base or scale and GET and 
PUT statements in either scientific or 
commercial environments . 



A = B * C + D; 



The instructions produced from the assign- 
ment statement might be as follows : 

• In-line instruction to load B into 
some register. 

• In-line instruction to multiply C 
(floating-point multiplication) with 
the contents of this register. 

• In-line instruction to add D 
(floating-point) to the contents of 
this register. 

• Calling sequence (s) to convert the 
contents of this register to fixed 
decimal form. 

• In-line instruction to store the 
result in A. 

Calling sequences can be avoided in 
some cases, e.g., in the example shown 
above by giving A the attributes FLOAT 
DECIMAL instead of FIXED DECIMAL. To save 
storage, the user should, therefore, write 
his programs in such a manner as to avoid 
unnecessary calling sequences. 

The above example shows that a series 
of instructions is generated for a single 
PL/I statement. The number of generated 
instructions depends on the form and com- 
plexity of the respective statement. The 
number of instructions generated for a 
source-text DO statement, for instance, 
depends on the complexity of the expre- 



4. Parameters as well as BASED and 

EXTERNAL data require 4 bytes in addi- 
tion to the storage requirements of 
the data item. 

Thus, if 5000 bytes are available for 
the object program, the user may assume 
that approximately 125 PL/I statements 
(scientific environment) or 178 PL/I sta- 
tements (commercial environment) can be 
accommodated in this area. If the program 
exceeds this number of statements, the 
user must either shorten the function of 
the program or use the overlay feature. 
(Refer to the section Overlay.) 

Note; If listing of source-program state- 
ment numbers in case of execution-time 
errors is requested (by specifying STMT in 
the PL/ I PROCESS card), the additional 
storage requirements are 4 bytes for each 
time the statement number appears in the 
object-program listing. 

Problem Analysis Example 

A tape system that has a storage capacity 
of 16K is used for maintaining files. The 
problem program consists of 3 phases. 
Phase 1 reads transaction cards (one 80- 
column card per transaction) and sorts, 
edits, and writes the contents of these 
transaction cards on a magnetic tape file. 
Phase 2 reads the old master file, a tran- 
saction card, and writes a new master file 
record. Both of these operations involve 
magnetic tapes for old and new master 
records. An exception report is written, 
if necessary, on a fourth magnetic tape. 
Phase 3 takes the exception file and pre- 
pares it with appropriate headings. 
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In the following example, only the 
storage requirements for phase 2 are 
examined. 



FILE DESCRIPTION 

01 d_ Master File: Unblocked, 320 -character 

records of fixed length. 

M:§^_i3as ter _Fils : Unblocked, 320-character 

records of fixed length. 

Transaction File . Unblocked 80-character 

records of fixed length. 

Exce£tion_Fi le : Unblocked 100-character 

recordfe~'of fixed length. 



DATA ASSUMPTIONS 

Due to the requirements of temporary 
storage, arithmetic statements, etc., 50 
variables and constants are used in addi- 
tion to the data read from and written 
into files. All data is describable in 
terms of pictures and character strings; 
no data is read or written in packed mode. 



2. Non-I/0 Subroutines 
Numbers 11 and 12 

TOTAL 

3- File_ Descriptions 

a. Buffers - 

b. DTF tables - 

c. Appendages - 

d. IOCS logic modules 



I/O Subroutines 
Number 6 

TOTAL 



640 bytes 



8 20 bytes 

368 bytes 

96 bytes 

690 bytes 

1974 bytes 



65 2 bytes 



OTHER ASSUMPTIONS 

1. Each file has only one buffer. 

2. The data is processed in its respec- 
tive buffer by use of the READ SET or 
LOCATE SET Statements. 

3. The program can be written in one 
block. 

U. The problem does not necessitate 
inter-phase communication. 

5. If conversions from numeric fixed to 
coded fixed become excessive, the user 
will convert the data items once and 
use the coded fixed form for subse- 
quent computations. 



Storage Requirements 

The storage requirements are as follows: 

1. Data 

aT" Data read from, or written into, 
files are accounted for in 
buffers. 

b. 30 variables (XXXX.XX) 120 bytes 
20 constants (XXX. XX) 60 bytes 

c. Descriptors approximately 150 bytes 

TOTAL approx. 33 bytes 



160 bytes 

150 bytes 

60 bytes 

1500 bytes 

1870_bYtes 



5. 03?§^he§^ 

a. Static - approx. 

b. Dynamic - approx. 

c. Frologue - approx, 

d. PL/I control - approx. 

TOTAL approx, 

6- DOS/TCS Control Program 
approx. 6150 bytes 



GRAND TOTAL approx. 11,616 bytes 

This means that approximately 4,770 
bytes of storage are available for the 
actual program, so that the approximate 
number of PL/I statements that would fit 
into storage is 160. 

After having programmed the problem, 
the user would determine whether or not he 
can change the buffering to allow for 
faster transaction processing. If the 
data read and/or written are changed into 
packed form, the buffer requirements are 
reduced, and the non-I/C subroutines of 
640 bytes would not be required. This 
would allow for approximately 30 addition- 
al PL/I statements. 



Overlay 



If certain parts of an object program are 
not required in storage throughout its 
execution and never simultaneously 
required in storage, the same storage area 
can be used to store these parts to reduce 
the overall requirements of the program. 

Each part of the program that will 
reside in storage only for a fraction of 
the execution time is referred to as an 
overlay. The MAIM procedure must not be 
used as an overlay. Each overlay as well 
as any portion of the program that resides 
in storage throughout the execution is 
referred to as a phase. A phase consists 
of one or more external procedures. 

The PL/I subset does not provide direct 
overlay facilities. However, overlays can 
be performed by using the library subrou- 
tine OVERLAY that provides a link to the 
operating system which, in turn, loads the 
actual overlay. (Refer to the SRL publi- 
cations describing the DOS/TOS control and 
service programs.) The statement calling 
the overlay must be coded as follows: 

[label:] ... CALL OVERLAY 

(character string expression - max. 
length 8) 



For example, LINK: 
(•PHASES*) ; 



CALL OVERLAY 



The overlay call activates the OVERLAY 
subroutine and transmits the name >of the 
phase to be fetched to the control pro- 
gram. The control program locates this 
phase on the external medium. The phase 
is then loaded into storage. It must not 
overlay the fetching procedure. Finally, 
control is returned to the fetching 
procedure. 



Rules For Using Overlay 

The following 17 rules should be observed 
when using overlay calls: 

1. After the phase has been entered in 
storage, it must be activated by means 
of a call to the procedure name or any 
of its entry points. 

2. The phase name is independent of the 
procedure name. It is assigned by 
means of a PHASE card during proces- 
sing by the Linkage Editor. 

3. A fetching phase (i.e., a phase acti- 
vating an overlay) may have been 



fetched into storage by a preceding 
fetching phase. A series of succes- 
sive fetching phases is referred to as 
a tree structure (see Figure 65). The 
principal fetching phase of a tree 
structure is referred to as the root. 
A phase within the tree structure 
which is not a fetching phase is 
referred to as a leaf. 

4. A fetching phase may fetch any phase 
lower than itself in the tree struc- 
ture, provided the fetched phase is on 
the same branch as the fetching phase. 

5. If a phase fetches a phase more than 
one level below it, an empty space is 
left in storage for each phase between 
the fetching and the fetched phase. 

6. The root cannot be overlaid. It 
resides in storage throughout the 
execution of the problem program, 

7. A phase may be activated at any time 
after it has been fetched, provided it 
has not been destroyed. 

8. Fetching a phase already fetched into 
storage causes a new copy of that 
phase to be fetched into storage. All 
variables of that phase which are in 
static storage have no known value. 

9. Data to be known in more than one 
phase may be given the EXTERNAL attri- 
bute or be transmitted through argu- 
ment lists of the CALL statement. 
External names that are to be common 
to more than one phase below the root 
level must be declared to be external 
both in the affected phases and in the 
root. For larger volumes of data, the 
use of the EXTERNAL attribute general- 
ly requires less storage than argument 
transmission. Where the argument 
names change, argument transmission is 
normally more economical than giving 
the data the EXTERNAL attribute. 

10. External names of procedures to be 
fetched must be unique (see Figure 
65.) 

11. A library subroutine is incorporated 
in every phase in which it is used if 

a. the subroutine is used in a proce- 
dure below the root level; and 

b. that subroutine is not in the 
root. The multiple appearance of 
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the subroutine can be avoided by 
incorporating it in the root 
through the use of an INCLUDE sta- 
tement during link-editing so that 
it appears only in the root. 



ROOT 



@ 



rn 


















1 










1 


M 




N 




O 



Note: The ROOT phase may fetch any phase, A through O. Phase A 

may fetch any phase, C through L. Phase B may fetch any phase, 
M through O. Phase C may fetch phases F and G. Phase E may 
fetch any phase, H through L. Phase H may fetch phases J 
through L. Phases D, M, N, O, F, G, I, J, K, and L are 
leaves. 



Figure 65, 



Schematic Representation of a 
Tree Structure 



12. 



Note: Care should be taken if relo- 
catable modules that are not PL/I 
library subroutines are to be included 
into more than one phase by the auto- 
link feature. For details, refer to 
the SRL publications describing the 
DOS/TOS system control and system ser- 
vice programs. 

If many phases from different branches 
of the tree structure activate the 
same procedure, this procedure may be 
incorporated in the root in a manner 
similar to the inclusion of subrou- 
tines (see rule 11). 



13. 



If (1) the declara 
made internal to s 
not the root, (2) 
in this phase, and 
about to be overla 
another branch of 
the user must clos 
it is destroyed, 
does not apply if 
both in the root a 



tion of a file is 
ome phase which is 
thi s file is Oldened 

(3) the phase is 
id with a phase from 
the tree structure, 
e this file before 
This restriction 
the file is declared 
nd in a lower phase. 



Note: If the PL/I standard files are 
used (by a GET or PUT statement) in a 
phase other than the root, these files 
must either be used in the root phase, 
too, or in a phase that will not be 
further overlaid. Another possibility 



is to include the corresponding 
modules in the root by means of the 
Linkage Editor control statements 



INCLUDE IJKSYSA (for PUT) 
INCLUDE IJKSYSI (for GET) 



In all other cases, the standard files 
cannot be closed, and an error will 
occur at End-of-Job= 

1h. If the object-time diagnostic messages 
are to include the numbers of the 
source statements causing the errors, 
STMT must be specified in the PROCESS 
card for at least the first external 
procedure contained in the root phase. 

15. The time to find and transfer a phase 
to core storage requires between 200 
and 500 msec for DOS, depending on the 
phase length* A lOK phase, for 
example, would require approximately 
350 msec. 

16. The time required to find and transfer 
a phase to core storage for TOS 
depends on the physical location of 
the phase on SYSLNK. 

17. Different modules to be included from 
the relocatable library may be ident- 
ical except for one or more additional 
entry points in one of these modules. 
If the module without the additional 
entry point (s) is contained in the 
root phase, calling of the module with 
the entry point (s) in overlay phases 
will result in an error during 
link-editing. 

For instance, the PL/I library rou- 
tines IJKTSTM and IJKTLCM have the 
following entries: 



r T T 1 

I Module Name | IJKTSTM | IJKTLCM j 



1- 


4 + ^ 


i Entry 


j IJKTSTM 1 IJKTSTM | 


1 Names 


1 IJKTSTN 1 IJKTSTN | 


I 


1 IJKTSTR 1 IJKTSTR | 


1 

I 


1 1 IJKTLCM 1 



(IJKTSTM is used for stream I/O, 
IJKTLCM is used for stream I/O with 
COLUMN or LINE.) 

If IJKTSTM is contained in the root 
phase, calling of IJKTLCM in an over- 
lay phase will result in an error dur- 
ing link-editing. To avoid such 
errors, the module containing the 
additional entry (IJKTLCM in this 
case) must be included in the root 
phase by means of an INCLUDE 
statement. 
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Overlay Example 

Assume that some program consists of one 
external procedure, which is a single 
block. Compilation of this procedure on a 
system with a storage capacity of 16K pro- 
duces an object program that requires 2 OK. 
The storage requirements for the individu- 
al parts of the program are as follows: 



DOS/TOS control program 

Overhead 

Data 

Subroutines including 

logical IOCS 
Object program 



- 6K 

- 2K 

- 2K 

- 5K 

- 5K 



Actually, the program requires only 19 K 
under the assumption that IK of data is 
automatic and IK is static. However, 20 K 
is required when the data is allocated. 

In order to make the object program run 
on a system with a storage capacity of 
16K, it is segmented into 8 phases. The 
root, which is located behind the DOS/TOS 
control program, contains the MAIN proce- 
dure and the subroutines. Thus, the root 
plus the DOS/TOS control program may 
require llK plus the overhead and program 
requirement of 2K, i.e., a total of 13K. 
Since the PL/I control program is in the 
root phase, the total overhead for the 
non-root phases is approximately .5K. 

This remaining overhead increases 
slightly because there are now 8 separate 
blocks, each of which with its own over- 
head. The allotment of this remaining 
overhead may result in .25K per block. 
Due to these changes, the program logic 
must be slightly changed and extended to 
allow for the overlaying. This brings the 
requirement for the object program to 
about .7K per phase. Since each phase 
requires less than IK and the root plus 
the control program requires 15K, the pro- 
gram will now run on a system with a 
storage capacity of 16K. The root will 
fetch the first phase (named PHSEl) and 
activate it. Control is then returned to 
the root, and the second phase (named 
PHSE2) is fetched and activated. This 
process is repeated until the eighth phase 
has been executed. This completes the 
processing of one block of input data, and 
the process is then repeated. The names 
of the procedures shown below are A for 
the root and Bl, B2, ...., B8 for the 
phases. 

A:PROCEDURE OPTIONS (MAIN); 

DECLARE (data items) EXTERNAL; 
ON ENDFILE (file-name) action; 
BEGIN: CALL OVERLAY (* PHSEl'); 
CALL Bl; 

CALL OVERLAY (•PHSE2'); 
CALL B2; 



CALL OVERLAY ('PHSES*); 

CALL B8; 

GO TO BEGIN; 

END 
B5 : PROCEDURE ; 
DECLARE (data items) EXTERNAL; 

source text 

RETURN; 
END; 

For DOS, the additional time required 
per block of input data when using the 
overlay feature is approximately 4 
seconds. For TOS, the additional time 
required depends on the number and order 
of the phases. In the above example, the 
time increase is about the same for DOS 
and TOS, 

Processing of Overlays by The Linkage 
Editor 

All phases of one program are processed by 
the Linkage Editor prograir in one single 
job step. Therefore, only one // EXEC 
LNKEDT statement must be given for a 
multi-phase program. Each phase requires 
one PHASE statement, which must immediate- 
ly precede the input for this phase. The 
ENTRY statement, if used, must be the last 
statement in the input stream to be writ- 
ten on SYSLNK. A multi-phase program must 
contain one external procedure with the 
option MAIN. This external procedure must 
appear in the physically first phase, 
i.e., in the root phase. 

If programs that contain overlays are 
to be processed by the Linkage Editor pro- 
gram, a PHASE statement of either one of 
the following three formats must be used: 

1. PHASE phasename.ROOT 

This format must be used for the root 
phase. It must be the first PHASE 
statement in the input stream. 

2. PHASE phasename,* 

This format of the PHASE statement 
causes the subsequent phase to be 
loaded beginning at the next double- 
word boundary. The use of this state- 
ment is recommended for the second 
phase, 

3. PHASE phasename, symbol 

Symbol is either a previously-defined 
phase name or an entry name appearing 
in a previous phase (except in the 
root phase) , This format of the PHASE 
statement causes the next phase to be 
loaded beginning at the address of the 
symbol . 

The syntax rules for the PHASE state- 
ment are as follows : 
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1. h phase name must be from 5 to 8 
characters long. 

2. All phase names of a program must be 
identical in their leftmost four 
characters. 

Ngte: Different programs (tree struc- 
tures) must differ in the first four 
CiiSraCi-srs Gj. tuejir puase names xn 
order to avoid incorrect storage 
allocation- 

3- The phase names must be identical to 
the values of the character-string 
expressions (except for blanks on the 
right-hand side) that are used as 
arguments in the OVERLAY statement. 

When link-editing multiphase foreground 
programs, the ACTION statement with the 
operand Fl or F2 must be used because, 
otherwise, the PHASE card for the first 
phase could not have the ROOT operand. 
The first three characters of the phase 
names of a multiphase foreground program 
should be FGP to have them retrieved fast- 
er from the core- image library. 



r-T- 



// JOB MYOVLAY 
// OPTION LINK 

PHASE 0VLAY1,R00T 
// EXEC PL/ I 

RT:PROCEDURE OPTIONS (MAIN): 

RU: ENTRY 

CALL OVERLAY ( ' 0VLAY2 ' ) ; 

CALL OVERLAY ( ' 0VLAY3 ' ) ; 

CALL E; 

END; 



/* 



/* 



INCLUDE JKLM 
PHASE 0VLAY2, * 
INCLUDE 
deck XYZ 



PHASE 0VLAY3,0VLAY2 
INCLUDE MYPROG 
// EXEC PL/I 

E : PROCEDURE ; 

END; 
/* 

ENTRY RU 
// EXEC LNKEDT 
// EXEC 
/£ 



Figure 66, Sample Program to be Processed 
by the Linkage Editor 

Figure 66 shows a sample program to be 
processed by the Linkage Editor. The num- 
bers at the left-hand margin are not part 
of the coding; they serve as reference to 
the explanations only. 



Explanation 

1 Causes loading of phase CVLAY2. 

2 Causes loading of phase CVLAY3. 

3 Activates procedure E in phase 0VLAY3. 
It is assumed that phase 0VLAY3 has 
been loaded previously and has not been 
destroyeu, (for example, by reloading 
phase CVLAY2). 

4 The module JKLM that is cataloged in 
the relocatable library is to be used 
in 0VIAY2 and 0VLAY5. Therefore, it is 
included in the ROOT phase by an 
INCLUDE statement. 

5 This statement causes three actions: 

a. It signals that the input stream of 
OVLAYl is terminated. 

b. The modules that are contained in 
the relocatable library and 
required for OVLAYl are retrieved 
from the library by the autolink 
feature in order to complete 
OVLAYl. 

c. Phase CVLAY2 is loaded beginning at 
the first double-word boundary fol- 
lowing the last module of OVLAYl. 

6 This statement causes three actions: 

a. It signals that the input stream of 
0VLAY2 is terminated. 

b. The library modules that are 
required for phase 0VLAY2 and not 
contained in the ROOT phase 
(OVLAYl) are retrieved from the 
library by the autolink feature. 

c. The starting point of 0VLAY3 is 
determined to be the same as that 
for CVLAY2. 

7 This statement causes four actions: 

a. It signals that the input stream 
for the program is terminated. 

b. The library modules that are 
required for phase 0VLAY3 and not 
contained in the RCOT phase 
(OVLAYl) are retrieved from the 
library by the autolink feature, 

c. RU is determined to be the starting 
point for the execution of the 
program, 

d. The starting point of the dynarric 
storage area is determined to begin 
on the first double-word boundary 
following 0VLAY2 or 0VLAY3, whi- 
chever is longer. 



8 Fetches OVLAYl and transfers control to 
entry point RU. Note that only the 
ROOT phase is loaded by // EXEC. 

+ See PL/ I Procedures Contained in_t he 
Relocatable Libr ar y below . 

The structure of the resolved overlay 
scheme of the above example is shown in 
Figure 67. 



DOS/TOS 



OVLAYl < 



OVLAY2 < ■ - 



RT 



JKLM 



^ Modules included by the 
autolink feature, if any. 



XYZ 

) Modules included 
by the autolink 
feature, if any. 



OVUY3 < 



Structure of the Resolved Overlay Scheme - R. 



MYPROG 



Modules included 
by the autolink 
feature, if any. 



>■ Dynamic storage 



Figure 67, Structure of the Resolved 
Overlay Scheme 



PL/I Procedures Contained in The 
Relocatable Library- 
precompiled PL/I procedures may be inco- 
rporated in the relocatable library by 
using the DOS/TOS MAINT service program. 
A module is retrieved from the library and 
incorporated in the object program by the 
autolink feature when the name of the 
module is specified for the first time 
either in a PL/ I function reference or in 
a CALL statement. 



No module is retrieved from the library 
if only secondary entry points are 
referred to in the calling procedure(s) . 
In this case, a statement of the format 



INCLUDE module-name 



is required to include the module in the 
object program. On the other hand,, inco- 
rporation by the autolink feature can be 
suppressed for a specific module by refer- 
ring only to secondary entries of that 
module. To obtain the same result as by 
calling the primary entry point, the pro- 
grammer may insert a statement of the 
format 

ENTRY secondary-entry-name 

immediately behind the PRCCEDURE statement 
of the external procedure. 



N ot e; Although this description covers 
most of the applications of the overlay 
scheme, the reader should study the sec- 
tion covering the Linkage Editor program 
in the SRL publications that describe the 
DOS/TOS system control and service 
programs. 
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Program Listings 



SoufCe Pfogram Listing 

All source program cards are listed if the 
LIST option is in effect. Each card is 
printed as one line. The source state- 
ments are numbered sequentially starting 
at 1. The statement number is printed in 
print positions 1 through & of the line 
where the statement begins (right- 
aligned) . In case a line contains more 
than one statement, only the number of the 
first statement is printed. However, 
since the remaining statements are coun- 
ted, the next line again gives the correct 
statement number. 

Note: If comments or character strings 
are not correctly opened or closed in the 
source text, unpredictable diagnostic mes- 
sages may be produced. Also, the source 
statement numbering will be erratic. 

If the source statement contains any 
error (s), the statement number is used in 
the corresponding diagnostic message to 
clearly identify the statement in error. 
The diagnostic messages are listed in 
Appendix F, 

Column 1 of PL/I source program cards 
must always be blank. If column 1 of a 
source card contains any character, print 
positions 7 through 20 of the correspond- 
ing line in the source program listing -- 
i.e., the gap between the statement number 
column and the source statement column 
plus column 1 of the source card — are 
filled with asterisks to indicate this 
error. Columns 73 through 80 are ignored 
and may contain any information. 



Symbol Table Listing 



If the SYM option is specified, all sym- 
bols used in PL/I source programs are 
listed in the symbol table. The format of 
the symbol table is shown in Figure 68. 

The symbol table is listed even if 
NOSYM was specified in case a declaration 
contains an error or an external name is 
too long. 

The programmer is advised to examine 
the symbol table listing after the first 
compilation of a procedure to detect 
erroneously declared identifiers and iden- 
tifiers that may have been incorporated by 
default rules as the result of 
mispunching. 

The attributes ALIGNED or UNALIGNED, if 
specified for a major structure, are 
printed together with the elements of the 



structure, unless an opposite attribute 
has been explicitly declared for a parti- 
cular element. 



r T 1 

! Print I ', 

\ Positions j Contain 

J- 1 ___,„„^™^_-™^^ 

1-31 I user-defined name 



33-36 



internal representation 



38-39 i block number 



( Dxocx xevex numoer 



4 3-49 jone of the attributes ARRAY, 
I STRUCT., ENTRY, or BUILTIN* 



51-53 



logical structure level* 



+- 

55-61 jone of the attributes ARITHM,, 
I STRING, LABEL, POINTER, FILE, 
I or PICTURE* 



63-69 I one of the attributes DECIMAL, 
[BINARY, ALIGNED, UNAL, , CONST,, 
I or VARIAB, * 



71-75 jone of the attributes FIXED, 
IFLCAT, BIT, CHAR., or STERL* 



^ 

77-81 jthe precision or length* 



83-88 lone of the attributes STATIC, 
lAUTOM., BASED, PARAM., or 
IDEFIN.+ 

4- 



f- 



90-92 I one of the attributes INT or 
JEXT 

J. 

* if applicable 



Figure 68. Format of the Symbol Table 
Listing 



Any error detected during compilation in 
the declaration of the symbols is identi- 
fied in the symbol table. In this case, 
only the source program symbol, one of the 
messages listed in Figure 69, three 
asterisks, and the code pertaining to the 
message appear in the respective line of 
the listing. 



Message 12 appears with the first com- 
parand only. Comparison starts with the 
innermost block and proceeds either on the 
same nesting level according to the block 
sequence of the program, or to the block 
with the next higher nesting level. 
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Example : 

OUT: PROCEDURE; 

DECLA.RE E BINARY EXTERNAL; 
IN: PROCEDURE; 

DECLARE E DECIMAL EXTERNAL; 

END IN; 
END OUT; 

The message appears with the E in procedure 

IN. 



r T- 

Codel 



Message Text 



01 i SYNTACTICAL DECLARE ERROR. 



02 I CONFLICTING ATTRIBUTES. 



03 



04 



05 



06 



07 



08 



09 



OA 



OB 



OC 



OD 



OE 



OF 



10 



11 



PRECISION IS MISSING OR WRONG. 



BASE VARIABLE ITSELF IS DEFINED OR 
BASED. 



BASE OR POINTER INCORRECT. 



ATTRIBUTES OF SECONDARY ENTRY CON- 
FLICT WITH THOSE OF PRIMARY ENTRY, 



MULTI-DECLARED IDENTIFIER. 



ENTRY RETURNS VALUE WITH CONFLICTING 
ATTRIBUTES. 



INVALID STRUCTURE. (Any invalid 
element in a structure may invalid- 
ate the entire structure) . 



ARRAY TOO LONG. 



STRUCTURE TOO LONG, 



POINTER IN BASED STRUCTURE. 



TOO MANY ARRAYS. 



INVALID PICTURE. 



STRUCTURE LEVEL DEEPER THAN EIGHT 



+ . ^ External Symbol Table Listing 



NAME EXCEEDS 31 CHARACTERS IN 
LENGTH. 



EXTERNAL NAME EXCEEDS 8 CHARACTERS 
IN LENGTH. 



containing the external names in alphabetic 
order as well as the internal names and the 
statement numbers of those statements in 
which the names appear. References to 
identifiers in DECLARE statements or to 
incorrectly declared identifiers are not 
printed. 



Offset Table Listing 



The offset table listing is produced if the 
SYM option is specified in the OPTION sta- 
tement. The information is printed in four 
columns in hexadecimal notation. 

Internal Name. A variable or constant is 
listed in the offset table if (1) it is de- 
clared in the source text and (2) it 
appears either in the automatic or static 
storage area, and (3) has a fixed offset 
relative to the beginning of the respective 
storage area. 

Offset. This column gives the offset of 
the data item relative to the beginning of 
the automatic or static storage area for 
the corresponding block. 

Type. This column indicates whether the 
data item is contained in static or in 
automatic storage. 

Module_Of f s et . This column gives the off- 
set of the data item relative to the begin- 
ning of the module in which it appears. 
(Since the addresses in automatic storage 
are dynamically assigned, no offset rela- 
tive to the beginning of the module can be 
given for automatic data.) The absolute 
address of the data item contained in stat- 
ic storage can be determined by adding the 
load address of the module (to be found in 
the Linkage Editor storage map) to the 
value given here. 



! 12 I MULTIPLE DECLARATION OF EXTERNAL 
NAME INCONSISTENT. 

Figure 69. Error Codes Used in the Symbol 
Table Listing 



Cross -Reference Listing 

If XREF is specified either in the OPTION 
statement or in the PL/I PROCESS statement 
a cross-reference listing will be provided 



The external symbol table is produced if 
the SYM option is specified in the OPTION 
statement. It contains the following 
information: 

SYMBOL - the external symbol 

- either SD, LD, or ER 

- ESID number of control 
section that is referred 
to (for SD and ER) 

- begin address (for SD 
and LD) 

- end address (for SD 
only) 

- ESID number of control 
section that is referred 
to (for LD) 



column 
column 
column 


1: 
2: 
3: 


SYMBOL 

TYPE 

ESID 


column 


4: 


ADDR 


column 


5: 


LENGTH 


column 


6: 


ESID 
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Block Table Listing 



The block table listing is produced if the 
SYM option is specified in the OPTION sta- 
tement. The block table gives the number 
of the program block and the size of the 
corresponding DSA in hexadecimal notation. 



Object Code Listing 



The oxjject coae generatea ror a PL/I source 
program is listed following the offset 
table. The following should be noted: 

1. All addresses and operands are printed 
in hexadecimal notation. 



L'0104' is the label of the constant 
defined by the DC. A(N«0104«) refers 
to an entry point in the program that 
has the internal name. 

10. If a statement is preceded by more than 
one label, all labels are equated to 
the one directly preceding the state- 
msnt« For ti^e stateirent; 

A: B: C: X = Y; 

the following code would be generated: 



L* 


EQU 


♦ 


(for A) 


I' 


' EQU 


* 


(for B) 


L' 


MVC 


« • « « 





2. Length specifications in SS instrUc- 



ui«_>ia ULJ.KJ /; J u 



->c c i ^ .— .r-.i= 



4, 



j-Snguti ici op€CX^j.d^ ciiiia iinjiuiix^j xu XJL 

two lengths are specified. 

Operands of the form X'nnn* (b) repre- 
sent generated variables or constants, 
nnn is the displacement and b is the 
base register. 

Operands of the form N'nnn', where nnn 
is greater than or equal to 100, repre- 
sent internal names of declared items, 
(These can also be found in the symbol 
table.) 

Operands of the form N'nnn', where nnn 
is less than 100, represent internal 
names of PL/ I library subroutines. 

Labels of the form L'nnn* represent 
internal names of declared or generated 
labels. (Only declared labels can be 
found in the symbol table.) 

Operands of the form N'nnn' that appear 
in the instructions BC, BAL, or BCT 
represent internal names of either de- 
clared or generated labels, 

A 'constant' of the form X'' has the 
same function as the assembler instruc- 
tion EQU *, 

An instruction of the form 

L'nnn' DC A (N'nnn') 

does not represent an address constant 
of itself. L'nnn', in this case, is 
the label of the constant, whereas A( 
N'nnn') refers to an entry point of 
that internal name in the program. For 
example, in the instruction 

L'01Q4' BC A(N'010'4') 



11, The number of the source statement for 
which the object code is generated is 
printed at the end of the specific part 
of the object text. The statement 
number may appear more than once if the 
respective source statement was broken 
down into logical parts during 
compilation. 



Statement Offset Listing 

If LISTO is specified in the PROCESS card 
the statement numbers and the relative 
location of the end of each statement 
within the object module is printed. LISTO 
overrides LISTX, i,e,, if LISTO and LISTX 
are specified, the LISTX option is ignored 
because the object code listing and the 
statement offset listing cannot be printed 
together. 



Compile-Time Diagnostic Messages 

Errors caused by non-observance of language 
rules or restrictions in the source text 
are detected by the compiler. A diagnostic 
message is printed for each detected error 
following the source listing. For a state- 
ment containing one or more errors, several 
diagnostic messages may be printed. 

The individual diagnostic error messages 
are listed in Appendix F. 



Object-Time Diagnostic Messages 

Errors that occur during execution of PL/I 
programs cause the printing of an object- 
time diagnostic message. For the format of 
this message and for an explanation of the 
message codes that may be included in the 
message, refer to Appendix G. 
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Appendix A. Conversion Subroutines 



r T 

No, and 
intern, 
name 

+- 



Function 



Reason for Inclusion 
in Object Program 



+- 



Size (in Bytes) 



1 

IJKVECM 



Converts input data 

from F or E notation to an 

internal intermediate form 



F or E format has appeared 
in an input statement 



40a 



IJKVCEM 



Converts data from an internal 
intermediate form to F or E 
format in preparation for output 



F or E format has appeared 
in an output statement 



1024 



IJKVPCM 



Converts data in storage in 
coded fixed decimal form to an 
internal intermediate form 



Coded fixed decimal expres- 
sion appears in an output list 

or 
Coded fixed decimal data 
requires conversion to float- 
ing scale or binary base 



68 



IJKVCPM 



Converts data from an internal 
intermediate form to coded 
fixed decimal form 



! 5 {Converts data stored in 
IJKVFCM I numeric float form to an inter- 
IJKVNPMInal intermediate form 



Coded fixed decimal variable 
appears in an input list 

or 
Whenever a conversion to 
coded fixed decimal is required 



+- 



A numeric float variable 
appears in an arithmetic 
expression or in an output list 



4- 



214 



492 



IJKVCFM 
IJKVPNM 



Converts data in an internal 
intermediate form to internal 
numeric float 



Numeric float variable 
appears in an input list 

or 
appears on the left side of an 
assignment symbol 



680 



7 
IJKVBCM 



Converts data in storage in 
fixed binary form to an inter- 
nal intermediate form 



Integer binary fixed expres- 
sion appears in an output list 



60 



8 
IJKVCBM 



Converts data in an internal 
intermediate form to fixed 
binary form 



Binary fixed variable appears 
in an input list 



238 



IJKVTCM 



Converts data from coded float- 
ing point form (short or long 
word) to an internal intermedi- 
ate form 



Coded float expression or non- 
integer binary expression^ 
appears in an output list 

or 
Coded float or non- integer 
fixed binary expression is 
assigned to a numeric decimal 
variable or a coded fixed 
decimal variable 



3202 



10 
IJKVCTM 



Converts data from an internal 
intermediate form to coded 
floating form (short or long) 



Coded float variable appears 
in an input list 
or 
Conversion to coded float is 
required from either numeric 
data or coded fixed decimal 



3922 
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No. and 
intern, 
name 



11** 
IJKVNPM 



Function 



Converts data from numeric 
fixed form to coded fixed 
decimal form^ 



Numeric fixed decimal number is 
used in an arithmetic 
^expression or in an output list 



Reason for Inclusion 
in Object Program 



Size (in Bytes) j 



368 



125 



T.TTCV7PMM 



Converts data from coded fixed 
decimal form to numeric fixed 



Niimeric fixed decimal number 
appears on the left of an 



I o o *i m-*r 



.-1- .-T.mV^^l r-.r- -i rs 



j~ \j±. J.H an 



input list 



316 



-H 



13 

IJKVRPM 



Converts from numeric fixed 
sterling to coded fixed decimal 



Numeric sterling field is used 
in an arithmetic expression or 
in an output list 



796 



m 



IJKVPRM 



Converts from coded fixed 
decimal to numeric fixed 
sterlina 



Numeric sterling number 
appears on the left of an 
assignment syninol or in an 
input list 



1252 



15 
IJICVGIM 



Converts character string to 
bit string 



Conversion to bit string from 
character string form is 
required - 



25U 



IJKVIGM 



string 



CUIl VtJitiXUII CO CXidiciCCfciJC 

string from bit string is 
required or a bit-string 
expression appears in an 
output list 



XHO 



-^ 



17 
IJKVBTM 



Converts fixed binary data to 
coded float 



Conversion from binary 
fixed to coded float is 
required 



132 



18 

rKVTBM 



Converts coded float data to 
fixed binary 



Conversion from coded 
float to fixed binary is 
required 



228 



^The only way for a non- integer fixed binary number to appear is if the result of a j 
division of one fixed binary integer by another results in a non- integral value or by j 
use of any of the built-in functions PRECISION, BINARY, or FIXED. j 

i 

^Also requires a table of 128 bytes. Subroutines 9 and 10 require this table. If both| 

subroutines appear, the table is in storage only once. | 

I 

^Any picture data represented by [9. . . ] [V] [9 . . .] (T] is converted to and from coded | 

fixed decimal by a single in-line instruction and requires no subroutines. | 

I 
"♦Subroutine 11 is a subset of subroutine 5. If 5 is present, 11 is not. | 

I 
i ^Subroutinti 12 is a subset of subroutine 6. if 6 is present, 12 is not. | 

L . J 
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Appendix B. Possible Combinations of Data Conversions 







FORMAT ITEMS 
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Z 
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ta 


to 

LU 
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F 


NP 


NP 


NP 


NP 


1,4 


1,4, 
12 


1,10 


1,6 


1,4, 
14 


1,8 


NP 


NP 


NP 


NP 


E 


NP 


NP 


NP 


NP 


1,4 


1.4, 
12 


1,10 


1,6 


1,4, 
14 


1,8 


NP 


NP 


NP 


NP 


A 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


X 


NP 


NP 


NP 


B 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


15 


NP 


NP 


CODED FIXED DECIMAL 


2,3 


2,3 


NP 


NP 


IL 


12 


3,10 


3,6 


14 


IL 


NP 


IL 


NP 


NP 


NUMERIC FIXED DECIMAL 


2,3, 
11 


2,3, 
11 


NP 


NP 


11 


11,12 


3,10, 
11 


3,6, 

n 


11,14 


11 


IL 


11 


NP 


NP 


CODED FLOAT 


2,9 


2,9 


NP 


NP 


4,9 


4,9, 
12 


IL 


6,9 


4,9, 
14 


18 


NP 


18 


NP 


NP 


NUMERIC FLOAT 


2,5 


2,5 


NP 


NP 


4,5 


4,5, 
12 


5,10 


5,6 


4,5, 
14 


5,8 


IL 


5,8 


NP 


NP 


NUMERIC STERLING 


2,3 
13 


2,3 
13 


NP 


NP 


13 


12,13 


3,10, 
13 


3,6, 
13 


13,14 


13 


IL 


13 


NP 


NP 


FIXED BINARY 


2,7 


2,7 


NP 


NP 


IL 


12 


17 


6,7 


14 


IL 


NP 


IL 


NP 


NP 


CHARACTER STRING 


NP 


NP 


X 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


IL 


15 


NP 


NP 


BIT STRING 


NP 


NP 


NP 


16 


IL 


12 


IL 


6,7 


14 


IL 


16 


IL 


NP 


NP 


LABEL 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


IL 


NP 


POINTER 


NP 


• NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


NP 


IL 



Legend: NP - Not permitted. 

IL - Done directly in-line; no subroutine required. 

X - Contained as port of edit-directed I/O pockage to be discussed in I/O chapter. 

The numbers indicate the applicable conversion subroutines listed in Appendix A. 
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r — T 

No 
I— + 



-T 

1 Size 



19 

I— 

20 

i— 
21 

1-- 
122 

h- 
j 

'23 



REPEAT 






BOOL 



I— + 



Name 



j. 

character string 

bit string 



INDEX 



SUBSTR 



|. 

character string 

character string 



Argument (s> 






I Name (s) | Bytes 
J. J. 



j Restrictions* cind Additional 
I Information 



bit strina 



! IJKKiiKA i 
i I' JKRBKB I 



292 



[IJKRGKM 

■+ \-- 

I IJKRBIM 



84 
292 



{Result iTiUst not exceed max. 
"I string length 






1 IJKRGIM 
j IJKRBBM 
j in-line | 






108 
424 



bit string 



I IJKVIIM I 
4. +- 

I in-line | 



180 



24 



UNSPEC 



bit string 



I Argument must not exceed 



1—4 



26 
h— + 



DATE 
STRING 

ROUND 



fIJKSDTM I 

-+— + 

I in-line | 

I IJKRUBM I 
I in-line | 

j in-line 

! IJKRMBX 
i IJKRMBN 



58 



-f- 
I 

148 I 

— i 

~ I 

278 

I 



27 
28 



29 

F~ 

30 

H- -I 

31 

I— 
32 






fixed binary 
fixed decimal 

float 

all fixed binary 



all fixed decimal | IJKRMPX | 

I IJKRMPN! 



386 



MAX/MIN 



all short float 



i IJKRMSX j 
I IJKRMSNj 



all long float 



I— + 
33 

1—4 



I IJKRMLX I 
I IJKRMLN I 

-+ +- 

I in-line | 

4 +. 

I IJKRWBM I 



132 
172 



"I Argument with differing data 
I attributes causes some of the 
I data to be converted to one of 

-|the four permissible types. 
I The choice depends on the 
I element of the highest 

"{stringency level. 



SIGN 



fixed binary 



f^va/i /iQ^^m^l 



356 I 
^ 



34 



TRUNG 



short float 



long float 



4 . ^ -{fixed decimal data. IJKRWPM is 

jlJKRWSM j 236 |used only for FLOOR and CEIL. 
4 + ^ 



1-— 4 
35 

H-4 

36 (CEIL 
L X 



-^— I- 



244 
are 
Contained in TRUNC. Entry points are 



I IJKRWLM I 
.X J. 

, Entry points 



FLOOR 



Contained in TRUNC 



IJKRT.. 
IJKRV.. 



r — T- 



I— + 



No 



Name 



I Argument (s) 
I 



Internal 
Name(s) 



Size 
in 
Bytes 



Restrictions and Additional 
Information 



j fixed binary 
I _ 



IJKRSBM 



200 



37 



MOD 



I fixed decimal 
f 



IJKRSPM 



265 



I Short float 
V 



IJKRSSM 



184 



38 

1— 
39 

I— 
HO 

H- 
41 

H- 

42 

I— 

43 






jlong float 



PRECISION 

HIGH 

LOW 

FIXED 

FLOAT 

BINARY 












IJKRSLM 
in-line 
in-line 
in-line 



192 















44 

H- 

45 
I— 

46 

I— 

j 47 

I— 

148 

V-- 

49 
50 



DECIMAL 

BIT 

CHAR 









Attributes of arguments must 
permit conversion specified by 
built-in function name. No 
subroutine is called if 
argument is already in re- 
quested form. Appropriate 
subroutines 1-18 are used. 
Choice depends on attributes 
of argument and built-in 
function name. (See 
Appendix A. 



SUM 
PROD 






in-line 
in-line 









ALL 
ANY 

4 

51|ABS 
j.«_|. 



1—4 



in-line 
in-line 






52 

I— 
53 

54 

I— 
55 

56 

l~^ 

57 



jexpr.l fixed binary 
|expr.2 integer 
j constant 



in-line 
IJKREBM 






92 



I Result 1 < 23^-1 
(IHEXIB) 






lexpr.l fixed deci- 
jmal, expr.2 integer 
j constant 



IJKREPM 



140 



I Result I < 101-5-1 
(IHEXID) 



expr.l short float, 
j expr.2 fixed binary 
with scale factor 



IJKRESM 



144 



I Result I < 7.2x10''' 



(IHEXIS) 



expr.l**expr ,2 j — 



lexpr-1 long float, 
I expr.2 fixed binary 
I with scale factor 
^ 



IJKRELM 



152 



I Result I < 7. 2x10'' 5 



(IHEXID 



lexpr.l short float 



IJKRXSA 



152 
(60,62) 



f- 



Expr.l > 0; expr.2 not integer 
constant or fixed binary; 
I result I < 7.2xlO''5 
( IHEXXS) 



^ 

lexpr.l long float 

I 

I 

I 

-X 



IJKRXLM 



168 
(61,63) 



Expr.l > 0; expr.2 not integer 
constant or fixed binary; 
I result I < 7.2x10''^ 
( IHEXXL) 
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r — T 

1 1 


j 


T T- 


Size 


-T 


— 1 


1 Noj Name 


I Argument (s) 


1 Internal j 


in 


[Restrictions and Additional 




1 1 




IName(s) I 


Bytes 


jlnf oritiation 




L L 


_i ____^.__ 


i L_ 




L . 




r r 


1 — ^^ 


T r 




— J. 




1 1 


[short float 


1 IJKQQSM 1 


176 


1 Argument = or 2.4xl0-''8 < 




|58| 
1 1 








[argument < 7.2xlO''5 
1 (IHESQS) 




1 1 cr\T\m 












r*""*! *^^^^ 


r~~ — — 


1 T~ 




_-i __. .-^ .= 




1 1 


1 long float 


1 IJKQQLM 1 


160 


1 Argument = or 2. 4x10-"^ a < 




!59! 








[argument < 7.2xl0'!'s 




1 1 

j.__4 

1 60| 


[short float 


IIJKQASM 1 




1 (IHESSQL) 

_4 

1 Argument < 174.6 


~^ 


232 


1 1 








I (IHEEXS) 




I- — ^ EXP 


1 


1 1_ 




-4 


— -f 


|61| 

! i 


[long float 


1 IJKQALM 1 


456 


1 Argument < 174.6 
1 (IHEEXL) 




L _^ J. . 




J L_ 




_X ;; 




r T 


1 


T r- 




t 


^^ 1 


• • 


■ — « ■_ JCT*_j_ 


1 T' TT^rf->T- (-til 1 


•^•7 '^ 


1 Ti ... ._.*•> .M._X- -rf^ T '^__^/\T*s. 




1 i 


I ^llUl. l^ J. XUCL C 


j XUXV^JLiO« j 


Z. 1 ^ 


J rtiyUUlCIiU i: / , Z.AXU - - 




1 /r- ni 1 


1 


1 T TTTy^T n'Ti 1 




1 /TTi-.-rKir^X 




1 \ 


1 


j XUJ\»^JLiOID| 

1 IJKQLSC 1 




I Kxririj^L^oy 




L .J T.nfi/T.nm c\/x nf^'^^ 


1 1 




_J _ 




f"^"""^ XJ\J\J/ Xj\J\3j.\J / iJ\J 


^ ^ J- 


'"****"~™"^ I "^ "^ ""*"'" 'f ' ** 




t 


■"""T 


1 1 


( long float 


1 IJKQLLA 1 


384 


1 Argument < 7. 2x10 's 




1631 
i 1 




1 IJKQLLB I 
1 IJKQLLC 1 




1 ( IHELNL) 




!.__+ 


— -1 


1 ^_ 




_4 


— -1 


1 1 


[short float 


1 IJKQSSD 1 


304 


11 Radian ArgI < 2J-8xpi 




16^1 
1 1 
i 1 




1 IJKQSSB 1 
1 IJKQSSC I 
1 IJKQSSA j 




lIDegree Arg} < 2^8x180 
1 (IHESNS) 




I' — -f SIN/COS/ 


1 


+ +_ 





-4 


— "i 


1 1 SIND/COSD 


[long float 


1 1 JKQSLD 1 


416 


11 Radian Argl < 250xpi 




!65| 
1 1 
1 1 




1 IJKQSLBJ 
1 ICfKQSLCJ 
1 IJKQSLAJ 




lIDegree Arg | < 2^0x180 
1 CIHESNL) 




L L 


___!______.___ 


X L_ 




L 




r r 


"""""x"*^*"**™""^ ^ 


T r 




T 


""^ 1 


1 1 


[short float 


1 I JKQTSB 1 


280 


11 Radian Argl < 2i-8xpi 




|66 j 
1 1 




i I JKQTSA j 




1 1 Degree Argl < 2=*-Sxl80 
1 (IHETNS) 




j. — -ITAN/TAND 


K- — — — ~" 


^. — _^™--|. — .-. 4_ 




_4 


— "i 


1 1 


1 long float 


1 I JKQTLB 1 


360 


1 [Radian Arg | < 250xpi 




|67| 
1 1 




1 IJKQTLA 1 




jl Degree Arg| < 2^0x180 
1 (IHETNL) 






\. : 


___ + 4- 




_4 


— \ 


1 1 


[short float 


1 1 JKQNSD 1 


400 


|0 < |X,Y1 < 7.2x10^5 




|68| 




1 IJKQNSBI 








1 lATAN(X) 




1 IJKQNSC 1 








1 |ATAN(Y,X) 




1 I JKQNSA [ 




1 (IHEATS) 




I- — ^ATAND(X) 
1 |ATAND(Y,X) 


L 


i i_ 




_4 




r 

|long float 


1 1 JKQNLD 1 


536 


10 < IX, Y| < 7.2x10'' = 




1 1 




1 IJKQNLBl 








|69| 
i 1 




1 IJKQNLC 1 
1 IJKQNLAJ 




1 (IHEATL) 




Y — 4 


— + 


4 4_ 




.4 


— -j 


|70| 


(short float 


j I JKQCSA 1 


208 


1 lArgI < 174.6 




1 1 




1 IJKQCSBl 


(60) 


* i (IHESHS) 




j— HSINH/COSH 
1711 


1 


4 4_ 




_4 




r 

|long float 


1 1 JKQCLA 1 


288 


1 lArgI < 174.6 




1 1 




1 IJKQCLBl 


(61) 


*i (IHESHL) 




L J. 


1 ; 


J. L_ 




_! 




r — r 


1 


^ 1. 




T 


""^ 1 


1721 
i 1 


1 short float 


1 1 JKQDSA 1 


212 
(60) 


1 lArgl < 7.2xl0''5 
*| (IHETHS) 




i- — -fTAKH 


j. 


4 4_ 




_4 __. 


— \ 


|73| 
1 1 


{long float 


1 1 JKQDLA 1 


288 
(61) 


llArgj < 7.2xl0'5 
*1 (IHETHL) 





L J.. 
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1— + 

74 

I— 

75 



No 



Name 



Argument (s) 



Internal 
Name(s) 



Size 
in 
Bytes 



Restrictions and Additional 
Information 



ATANH 



I— + 
76 

I— 

77 



short float 



IJKQBSA 



208 
(62)* 



|Arg| < 1 
(IHEHTS) 



I 

long float 



IJKQBLA 



280 
(63>* 



|Arg| < 1 
(IHEHTL) 



—I 



ERF/ERFC 



I— + 

78 



short float 



IJKQRSB 
IJKQRSA 



408 
(60)* 



|Arg| < 7.6 2x103' 
(IJEEFL) 



long float 



IJKQRLB 
IJKQRLA 



776 
(61)* 



|Arg| < 7.62x1037 
(IHEEFL) 



ADDR 



I— f 

79 



in-line 



NULL 



1—4 

80 



in-line 



ADD 



I— -I- 
81 



in-line 



DIVIDE 



1—4 

821 MULTIPLY 
J .. 



in-line 



in-line 

J. X 



*The subroutine whose number is given in parentheses is also used by 
this routine. 





BUILT-IN FUNCTIONS CONTAINED 


IN 


THE FULL- 


-SET 


LANGUAGE, BUT 


NOT 


IMPLEMENTED 




L 




IN THE D 


-LEVEL COMPILER 








J 


I 


ALLOCATION 


DATAFIELD 




LBOUND 




ONCHAR 




CNSOURCE 






COMPLETION 


DIM 




LENGTH 




ONCODE 




POINTER 






COMPLEX 


EMPTY 




LINE NO 




ONCOUNT 




POLY 






CONJG 


HBOUND 




NULLO 




ONFILE 




PRIORITY 






COUNT 


IMAG 




OFFSET 




ONKEY 




REAL 




L 












ONLOC 




STATUS 


J 
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Appendix D. I/O Subroutines 



T 

I 



I Internal j 

} M aiTiS { 3 / I D es cr ipt iorx 



Reason for Inclusion in 
Object Program 



Eytes I 



21 



Pagesize 



Stream 
Constructor I 



IJKTPSM ! Controls number of 

j lines on printed page 



The PAGESIZE option appears 
in an OPEN statement 



IJKTSTM 
IJKTSTN 
IJKTSTR 






Constructs a logical 
stream from physical 
record and vice versa 



Always present for files 
declared with the STREAM 
attribute 



674* 



31 



Stream 
Constructor!! 



IJKTLCM 
IJKTSTM 
IJKTSTN 
IJKTSTR 



Same as Stream Con- 
structor I except 
that LINE or COLUMN 
is used 



F 

HZ 



Format I 



Always present for files 
with the STREAM attribute, 
with format list containing 
LINE or COLUMN, or with PUT 
statement containing the 
LINE option 



876* 



IJKTFDM I Associates a variable 
with its editing 
descriptor 



GET/PUT FILE EDIT Statement 
appears in source program 



-f 

480 



52 



Format II 



IJKTGDI 
IJKTGDO 



Same as Format I 



GET/PUT STRING EDIT State- 
ment appears in source 
program 



414 



Consecutive 

Buffered 

Transmitter 



IJKTCBM 



I-- 

7 






Consecutive 

Unbuffered 

Transmitter 



Regional 
Transmitter 



IJKTCUM 



IJKTRGM 



Transmits data to/ 
from the buffer from/ 
to a record variable 
for consec. files 

Transmits data 
directly from/to an 
external device 
directly to/from a 
record variable 

Transmits data to and 
from a regional de- 
vice via a hidden 
buffer 



READ/WRITE/LOCATE/REWRITE I 552* 
statement is used for a 
consecutive buffered file 

READ/WRITE/REWRITE Statement | 252* 
is used for a consecutive 
unbuffered file 



READ/WRITE Statement is used I 39 8 
for a regional file 



Regional 
Extent I 



IJKTXRM 



Determines extent of 
regional file at open 
time and serves as 
file addressing rou- 
tine to subroutine 8 



A regional file exists 
for 2311 or 2314 



356 



10 



IJKTXRN 



Regional 
Extent II 

Indexed 

Sequential 

Transmitter 



11 



IJKTSIM 



Same as 9 

Transmits data to/ 
from indexed data 
sets in seq. access 
access 



A regional file exists | 378 
for 2321 

READ/WRITE Statement is used] 652 
for indexed sequential file 



12 



Indexed 

Direct 

Transmitter 



IJKTDIM 



— + 



Transmits data to/ 
from indexed data 
sets in direct access 



READ/WRITE Statement is used 
for indexed direct file 



540 



I/O Subroutines, Part 1 of 2 



100 



J.. T- .. 

I 

Number | Name 



i Internal | 

I Name (s) | Description 



[Reason for Inclusion in 
I Object Program 



-T 1 

I 
[Bytes 



13 i Display 



jIJKTDPD (Handles DISPLAY JDISPLAY statement appears |18U 
-I IJKTDPR I statement and REPLY j in source program | 

i [option I I 



lU I LI ST- I/O 



jIJKTLIM JHandles list-directed] GET [FILE/STRING] LIST 
I I input I 



1068 



15 lLIST-I/0 
I 

JL 



JIJKTLOM [Handles list-directed [PUT [FILE/STRING] LIST 
I [ output ( 
.X X x^ 



1076 



^Subroutines 2 and 3 are never both used in any object program. 

^Requires a 200-byte format scanner. May be required by either subroutine U or 5, 
but is present only once. 

♦Requires an additional subroutine of 100 bytes. May be required by several 
subroutines but is present only once. 



I/O Subroutines, Part 2 of 2 
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O 



ft 
(U 
3 

a 
fu 

Oi 

rD 

H 

tr 



Field 






-File 


Label Numb« 


r 






































































































2 


3 
File Identifier 


4 

File 
Serial 
>Jumber 


5 

Volume 
Sequence 
Number 


File 
Sequenctt 
Number 


7 
S ^ 


8 


9 

Creation 
Dote 


10 

Expiration 
Date 


11 


112 

Block 
Count 


13 
System Oxle 


14 
Reserved 


- 


CO 


-I- 


m 
































S 


a ftj 


00 r— 


fi 




^ 


9 


^ 


s? 












5 


■ 1 




b 


s 


« 


S 


5 






















R 


R 












S 



Version 
Number of 
Generation 



The standard tape file label format and contents ore as follows: 



File Security 



•d 

CD 

■ 

ST 
tr* 

Of 

cr 

(D 



FIELD 


NAME AND LENGTH 


DESCRIPTION 


FIELD 


NAME AND LENGTH 


DESCRIPTION 


1. 


LABEL IDENTIFIER 
3 bytes, EBCDIC 


Identifies the type of label 
HDR - Header — beginning of a data file 
EOF = End of File — end of a set of data 
EOV= End of Volume — end of the physicol reel 


9. 


CREATION DATE 
6 bytes 


Indicates the year and the day of th«! year that the 
file was created: 

Position Code Meaning 

1 blank none 
2-3 00-99 Year 
4-6 001-366 Day of Year 

(e.g., January 31, 1965 would be entered as 65031) 


2, 


FILE LABEL NUMBER 


Always a 1 


3. 


FILE IDENTIFIER 
17 bytes, EBCDIC 


Uniquely identifies tfie entire file, may contain only 
printable characters. 


4. 


FILE SERIAL NUMBER 
6 bytes, EBCDIC 


Uniquely identifies a file/volume relationship. This 
field is identical to the Volume Serial Number in the 
volume label of the first or only volume of a multi- 
volume file or multi-file set. This field v/ill normolly 
be niiiTieric (000001 to 999999) but may contain any six 
alphameric characters. 


10. 


EXPIRATION DATE 
6 bytes 


Indicates the year and the day of the year vi^en the 
file may become a scratch tape. The format of this 
field is identical to Field 9. On a multi-file reel, 
processed sequentially all files are considerad to ex- 
pire on the same day. 


11. 


FILE SECURITY 
1 byte 


Indicates security status of 1^ filei. 

= no security protection 

1 = security protecticm. AiMitional Identification of 
the file is rdiquired before it can b<9 processed. 
(Not used by DOS/ TOS) 


5. 


VOLUME SEQUENCE NUMBER 
4 bytes 


Irtdicates the oider of a volume in a given file or 
multi-file set. The first must be numbered 0001 and 
subsequent numbers must be in proper numeric sequence. 


6. 


FILE SEQUENCE NUMBER 
4 bytes 


Assigns numeric sequence to a file within c multi-file 
set. The first must be numbered 0001 . 


12. 


BLOCK COUNT 
6 bytes 


Indicates the number of data blocks written on the file 
from the last header Ic^el to the fint trailer label ex- 
clusive of tope marks. Count does nof include check- 
point records. This field is i»ed in Troiler Labels. 


7. 


GENERATION NUMBER 
4 bytes 


Uniquely identifies the various editions of the file. 
May be from 0001 to 9999 in proper numeric sequence. 


13. 


SYSTEM CODE 
13 bytes 


Uniquely identifies the programming iiystem. 


8. 


VERSION NUMBER OF 
GENERATION 2 bytes 


Indicates the version of a generation of a file. 


14. 


RESERVED 
7 bytes 


Reserved. Should be recordcid as blan!l(s. 
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R 



L 



Format 
Identifier 



Extent 
Count 



JL 



Bytes used in last 
block of directory 















9 


10 


11 

u. 
1 
0£ 


12 

8 
1 

O 


13 


14 


15 

ii 


16 
g 


17 


Secondary 
Allocation 

CO 








19 


20 


First Extent 


Additional Extent 


Additional Extent 








33 


Reserved 
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Extent 
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Sequence 
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Number 
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Format 1: This format is common to all data files on Direct Access Storage Devices. 
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FIELD 


NAME AND LENGTH 


DESCRIPTION 


FIELD 


NAME AND LENGTH 


DESCRIPTION 


1. 


FILE NAME 

44 bytes, alphameric 

EBCDIC 


This field serves as the key portion of the file label. 

Each file must have a unique file name. Duplication of 
file name will cause retrieval errors. The file name can 
consist of tree sections: 

1 . File ID is an alphameric name assigned by the user 
and identifies the file. Can be 1 -35 bytes if gene- 
ration and version numbers are used, or 1 -44 bytes 
if they are not used. 

2. Generation Number. If used, this field is separated 
from File ID by a period. It has the format Gnnnn, 
where G identifies the field as the generbtion number 
and nnnn (in decimal) identifies the generation of 
the file. 

3. Version Number of Generationi If used, this section 
immediately follows the generation number and has 
the format Vnn, where V identifies the field as the 
version of generation number and nn (in decimal) 
identifies the version of generation of the file. 

Note: The Disk Operation System compares the entire 
field against the file-ID given in the DLBL statement . 
The generation and version numbers are treated 
differently by Operating System /360. 


The remaining fields comprise the DATA portion of the file label: 


2. 


FORMAT IDENTIFIER 
1 byte, EBCDIC numeric 


1 = Fomnot 1 


3. 


FILE SERIAL NUMBER 

6 bytes, alphameric EBCDIC 


Uniquely identifies a file/volume relationship. It is 
identical to the Volume Serial Number of the first or 
only volume of a multi-volume file. 


4. 


VOLUME SEQUENCE NUMBER 
2 bytes, binary 


Indicates the order of a volume relative to the first 
volume on which the data fi lei resides . 


5. 


CREATION DATE 

3 bytes, discontinuous binary 


Indicates the year and the day of the year the file was 
created. It is of the form YDD, where Y signifies the 
year (0-99) and DD the day of the year (1 -366). 


6. 


EXPIRATION DATE 

3 bytes, discontinuous binary 


Indicates the year and the day of the year the file 
may be deleted. The form of this field is identical to 
that of Field 5. 


7A 


EXTENT COUNT 


Contains a count of the number of extents for this file 
on this volume. If user labels are used, the count does 
not include the user label track. This field is maintained 
by the Disk Operating System programs. 
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FIELD 


NAME AND LENGTH 


DESCRIPTION 


FIELD 


NAME AND LENGTH 


DESCRIPTION 


7B 


BYTES USED IN LAST BLOCK 
OF DIRECTORY 
1 byte, binary 


Used by Operating System /360 only for partitioned 
(library Structure) data sets. Not useo by the Disk 
Operating System. 


13. 


BLOCK LENGTH 
2 bytes, binary 


Indicates the block length for fixed length records or 
maximum block size for varid»le length blocks. 


14. 


RECORD LENGTH 
2 bytes, binary 


Indicates the record lenath for fixe<l length records or 
the maximum record length Foe varitible length records. 


7C 


SPARE 
1 byt* 


Reserved. 


15. 


KEY LENGTH 
1 byte, binary 


Indicates the length of the key portion of the data 
recorcb in the file. 


8 


SYSTEM CODE 
13 bytes 


Uniquely identifies the progrofmning system. The charac- 
ter codes that con be used in this field are limited to 
0-9, A-Z, or blanks. 


16. 


KEY LOOTION 
2 bytes, binary 


Indicates the tiigh order posrion of (ho data record.. 


9 


RESERVED 
7bytM 


Reserved 


17. 


DATA SET INDICATORS 
Ibyte 


Bits within this flekl ore used to in^licate thefolloytfir^i 
Bit 

If on. Indicates that this is the liisit volume on which 
this file normally rwides,, This bit is usmI by the 
Ditk Operating S)ntem 

1 If on, indicates that th<i data set described by this 
file must remain In the tomt abuilute location otn 
the direct access device. 

2 If cm, indicates that Block Length must always be 
a multiple of 7 bytes. 

3 If on, indicdtes that this dcita file ist security pro- 
tected; a password must l>e provided in order to 
access It. 

4-7 Spare. Reserved for Future use. 


10. 


FILE TYPE 
2byt«i 


The contents of this field uniquely identify the type of 
data fllei 

Hex 4000 ° Consecutive organization 

Hex 2000 - Direct-access orgonizotion 

Hex 8000 = Indexed-sequential oiganlzotioii 

Hex 0200 =>= Library organization 

Hex 0000 > Oiganizotion not defined in the file label. 


11. 


RECORD FORMAT 
1 byt* 


The contents of this field indicate the type of records 
contained In the files 

Bit 
Position Content Meaning 

and 1 01 Vorioble length reconk 

10 Fixed lei^th records 

1 1 Undefined format 

2 No track overflow 

1 File is organized using 
track overflow (Opera- 
tir« System/360 only) 

3 Unblocked r^scords 
1 Blocked records 

4 No truncoteil records 

1 Truncated records i n f i le 

5 and 6 01 Control character ASA 
code 

10 Control character 
machine code 

00 Control character r<t>t 
stated 

7 Records hove no keys 

1 Rftcoids ore urritten 
with keys. 


18. 


SECONDARY ALLOCATION 
4 bytes, binary 


Indicates the amount of storage to be requested for this 
data file at End of Extent. This field Is used by Optra- 
ting System /36P only. It is not use<i by the Disk Ope- 
rating System routinen. Th<» first byte of this field Ik 
an indication of the type of oilocatiion request. Hex 
code C2 (EBCDIC B) blocks (physical records), hex 
code E3 (EBCDIC T) indiccitm trackii, and hex cad» 
C3 (EBCDIC Q Indicates cylirtden. The next three 
bytes of this field is a binary number indicating how 
many bytes, tracks or cylinders ore requested. 


19. 


LAST RECORD POINTER 

5 bytes, <fiscontinuo(js binary 


Points to the last record wril'ten In ci sequential or 
partition-organization data set. Th«i format is TTRLL, 
where TT is the relative address of the track contai- 
ning the lost record, R is the ID of t^he last record, 
and LL is the number of bytes temolning on the track 
following the last record. If tlieentini field contains 
binary zeros, the last record pointer does not apply. 


20. 


SPARE 
2byles 


Reserved 


21. 


EXTENT TYPE INDICATOR 
1 byte 


Indicates the type of extent with which the followltng 
fields ore associated: 

HEX CODE 

00 Next three f leldK do not Indicate any extent. 

01 Prime area (Indexed Ssquentlol); or Consecutive 
area, etc., (I.e.,, the extent containing the 
user's data recordb.) 

02 Overflow area of an Indexed Strquential file. 

04 Cylinder Index of master Index area of an 
Indexed Sequential nie. 


12. 


OPTION CODES 
Ibyt* 


Bits within this fleU are used to indicate various options 
used in buildir« the Hie. 

Bit 

> If on, indicates data file was created tjt'tt^ Write 

Validity Check. 

1 -7" unused 
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FIELD 


NAME AND LENGTH 


DESCRIPTION 


FIELD 


NAME AND LENGTH 


DESCRIPTION 






40 User label track area. 

8n Shared cylinder indicator, where n=l, 2, or 4. 


25-28, 


ADDITIONAL EXTENT 
10 bytes 


These fields have the same format as the fields 21 -24 
above . 


29-32. 


ADDITIONAL EXTENT 
10 bytes 


These fields hove the same format as the fields 21-24 
above . 


22. 


EXTENT SEQUENCE NUMBER 
1 byta, binary 


Indicates the extent sequence in a multi-extent file. 


33. 


POINTER TO NEXT FILE LABEL 

WITHIN THIS LABEL SET 

5 bytes, discontinuous binary 


The address (format CCHHR) of a continuation label if 
needed to further describe the file. If field 10 indicates 
Indexed Sequential organization, this field will point 
to a Format 2 file label within this label set. Other- 
wise, it points to a Format 3 file label, and then only 
if the file contains more than three extent segments. 
This field contains all binary zeros if no additional 
file label is pointed to. 


J.'3. 


LOWER LIMIT 

4 byl'es, dIsconMnuous binary 


The cylinder and the track address specifying the 
starting point (lower limit) of this extent component. 
This field has the format CCHH. 


24. 


UPPER LIMIT 


The cylinder and the track address specifying the ending 
ooint (upper limit) of this extent component. This field 
has the format CCHH . 
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8 


9 


53 


54 


60 


!62| 


65 


68 


70 


71 


84 


90 


91 


92 


96 


100 


10^102 


103 


Displacement 



Field 



Name 



Description 



DLBL-EXTENT Indicator 



X'80' = Next EXTENT on new pack. 

X'40' = Last EXTENT 

X'20' = Bypass EXTENT (SD), or number of EXTENTS (DA or ISFMS). 

X'lO* = New value on same unit. 

X'08' = EXTENT limits omitted. 

X'04' = EXTENT converted to DASD address. 



2. 


Filename 


3. 


DA/IS Switch 


4. 


File ID 


5. 


Format ID 


6. 


File Serial Number 


7. 


Volume Sequence Number 


8. 


Creation Date 


9. 


Expiration Dote 



10. 



Reserved 



Same as field 1 except that only bits 4 ond 5 ore used for DA or ISFMS. 

File identifier including neneration and version numbers. 

If field is missing on DL3L card, filename padded with blanks is inserted. 

Numeric 1 is inserted. 

Volume serial number from first EXTENT. 

Always initialized to X'OOOV . 

Initialized with 3 bytes of XiOO'. 

If date is in the fomi YYDDD, it is converted to YDD. 

If dote is in retention period form, 1 to 4 chorocters, the field is padded with 

binary zeros. 

The retention period, ff specified, is converted to a 2-byte number and 
inserted in this field. 



Open Code 



DLBL type: 



S = Se<)uential 

D = Direct Access 

C or E = Indexed Sequential File Marragement System 



System Code 

Volume Serial Number 
EXTENT-Type 



15. 


EXTENT Sequence Number 


16. 


EXTENT Lower Limit 


17, 


EXTENT Upper Limit 


18. 


System Uhit Class 




System Unit Order 


19. 


2321 Lower Call 




2321 U^perCall 



Initialized to contain; 

DOS/360 VER 3. This field is not processed by DOS. 

Volume serial number for EXTENT. 

Same codes as in Format 1 label : 

X'OO' = Next three fields do not indicate any extent. 

X'OI' = Prime area (ISFMS) or consecutive area, etc., (i.e., the extent 

containing the user's data records). 
X'02' = Overflow area of an ISFMS file. 
X'04' = Cylinder index or master index of on ISFMS file. 
X'40' " User label track area. 
X'Sn' = Shared cylinder indicator, where n = 1, 2, or 4. 

Number of extents as determined by the EXTENT card sequence. 

Relative extent converted to the form HHnnT for// DLBL job control statement, or 
CCHH from // DLAB job control statement. 

Same "x field 16, but for upper limit. 

Device class and unit numbers. 



2321 EXTENT lov^er and upper limit bin numbers. 



Note: For Sequential Disk files, a complete 104-byte block is repeated for each new EXTENT. For Direct Access and ISFMS files, 
only fields 13 through 18 are repeated for each EXTENT. 

Format of DASD Label Information in Label Area Reserved by LABTYP Card 
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Appendix F. Compile-Time Diagnostic Messages 



In the list of diagnostic messages below, 
the message text is preceded by the message 
number and the applicable severity code. 
Where necessary, the messages are followed 
by an explanation, an example, a descrip- 
tion of the action taken by the system, and 
the response required from the user. 
Explanation, Example, and System Action are 
given only when the text of the message is 
not sufficiently self-explanatory. 

When no User Response is stated, the 
user should assume that he must correct the 
error in his source program unless the 
action taken by the system makes it unne- 
cessary for him to do so. However, even 
when system action successfully corrects an 
error, the user should remember that, if he 
subsequently recompiles the same program, 
he will get the same diagnostic message 
again unless he has corrected the source 
error. 

The format of the diagnostic messages is 
as follows: 

5xdddl nnnn C comment 

where: 

X may be one of the following 
characters: 

h if compilation must be terminated as 
a result of a job- control device 
assignment or option error or 

if an error is detected in the PL/ I 
PROCESS card. 

C if a logical error has been detected 
in a source statement. 

E if a syntactical error has been 
detected in a source statement. 

G if the source program is too long or 
causes a storage overflow. 

ddd is the number of the error message. 

For a message that is also printed on 
the console, the number is composed of 
only two digits. 

I indicates that the message is of 

information type and that no operator 
action is required. 

nnnn is the number of the statement in 

which the error was detected. This 



number is given only in 5C and 5E type 
messages. 



is the severity code, which may be one 
of the following: 



W = Warning. 

This code indicates that the compiler 
suspects an error although the program 
is written in legal PL/I language. 
The compiler takes no further action, 

E = Error. 

The program is in error. However, the 
compiler has taken appropriate correc- 
tive action. Execution of the program 
will be successful if this corrective 
action was adequate. 

S = Severe Error* 

The program contains errors which the 
compiler cannot correct, but which do 
not prevent the compilation from being 
continued. Execution of the generated 
object program will be unsuccessful, 

T = Termination, 

The source program contains errors 
causing the compilation to be ter- 
minated. Compilation ends after the 
messages have been printed. 

comment 

is a compiler- generated explanation of 
the type of error. 



The error messages are printed on the 
unit assigned to SYSLST if ERRS was speci- 
fied in the Job Control CFTION statement or 
in the PL/I PROCESS card. The error list 
is followed by a message resulting from all 
detected errors. This message gives the 
action taken by the compiler. 



If errors of the severity T are 
detected, the message is: 



5E01I JOBSTEP PL/I TERMINATED. 
OPTION RESET. 



LINK 



If no errors of the severity T, but 
errors of the severity S are detected, the 
message is : 

5E02I LINK OPTION RESET. 
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Since in the case of severe errors no | 5E03I POSSIBLE ERRORS IN SOURCE PROGRAM. 
linkage editing is possible, the // EXEC 
LNKEDT statement, if any, is flagged as 

invalid by the Job Control message ISlnD Note: One or more of the following four 
STATEMENT OUT OF SEQUENCE. diagnostic messages may appear after one of 

the messages 5C003I through 5C030I in order 
to give additional information. These four 
If only errors of the severity W or E messages are printed without message num- 

CHARACTER MARKED BY ASTERISK IS NOT IN 60 CHAR. SET. 

Note; This diagnostic message will only be printed for errors in DECLARE 
statements . 

THE PRECEDING ERROR CONCERNS THE VARIABLE NAMED variable name 

THE PRECEDIKG ERROR CONCERNS THE ATTR. FACTORIZATION BEGINNING WITH declare- 
statement item 

'....* REPRESENTS CHARACTER STRING CONSTANT. 

Explanation: Illegal use of character-string constant. Since external repre- 
sentation of the character- string constant is not available, the constant is 
replaced by four periods. 

Exain£le: DECLARE N PICTURE A' 99999'. Due to the illegal character 'A' the 
string^' 99999' is not recognized as numeric picture but as character-string 
constant. The following messages will be issued where xx represents the sta- 
tement number: 

5C019I XX S INVALID ATTRIBUrE(S) IGNORED. .A* .... * 

'..,.' REPRESENTS CHARACTER STRING CONSTANT. 

THE PRECEDING ERROR CONCERNS THE VARIABLE NAMED N. 

5A001I T NO COMPILER OUTPUT SPECIFIED IN OPTION STATEMENT. 

5A002I T NOT THE SAME OR WRONG MEDIUMTYPES FOR SYSOOl, SYS002, SYS003. 

Explanation: SYSOOl, SYS002, and SYS0 03 must be assigned to the same device 
type, i.e., either to magnetic tape drives^ or to 2311 or 231*^ DASD extents. 

5A003I T PARTITION SIZE TOO SMALL FOR THE 12K VARIANT, 

SAOOai W ASTERISK IS NOT FOLLOWED BY BLANK. CARD IGNORED. 

Ex p la nation: Refers to PL/I PROCESS card. A plus sign is treated as an 
asterisk. 

5A005I W ASTERISK AND BLANK (S) NOT FOLLOWED BY KEYWORD PROCESS. 

Explanation: Refers to PL/I PROCESS card. A plus sign is treated as an 
asterisk, 

5A006I W OPTION invalid option UNKNOWN. FOLLOWING TEXT IGNORED. 

Explanation: Refers to PL/I PROCESS card. 
5A007I W KEYWORD PROCESS NOT FOLLOWED BY BLANK. CARD INGORED. 

Explanation: Refers to PL/I PROCESS card. 
5A008I W PROCESS LIST TOO LONG. IGNORED IS invalid option 

Explanation: Refers to PL/I PROCESS card. 
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5A009I W PROCESS LIST TOO LONG. 



Explanation: Refers to PL/I PROCESS card. 

5A010I W COMMA NOT FOLLOSfED BY OPTION, 

Explanation; Refers to PL/I PROCESS card. 
SAO 11 I W OPTION NOT FOLLOWED BY COMMA. 

Explanation; Refers to PL/I PROCESS card. 
5C003I E LEVELNUMBER OF STRUCTURE ITEM TOO HIGH. ASSUMED TO BE level number 

Explanation; Level number must not be higher than 255- 
5C004I S NO OPTIONS LIST WITH ENVIRONMENT ATTRIBUTE. 

Example; DECLARE FIL FILE ENVIRONMENT INPUT; 

5C005I S OPTION LIST NOT CLOSED BY ). PARENTHESIS INSERTED AT END OF STATEMENT.. 

Explanation: This message concerns the ENVIRONMENT and the INITIAL 
attributes. 

Example: DECLARE FIL FILE PRINT ENV(MEDIUM(SYSLST, 1U03) F(80) ; 
5C006I S NO POINTER SPECIFIED FOR BASED ITEM. 

Example; DECLARE VAR BASED; 

5C007I S ERROR IN SPECIFICATION OF POINTER FOR BASED ITEM. IGNORED IS based data item 

Examples; 1, DECLARE B BASED (A,D); 
2. DECLARE C BASED (F(I)); 

5C008I S NO BASE SPECIFIED FOR DEFINED ITEM. 

Example; DECLARE X DEFINED; 
5C009I S ERROR IN SPECIFICATION OF BASE FOR DEFINED ITEM. IGNORED IS defined data item 
SCO 101 S ERROR IN RETURNS LIST. IGNORED IS invalid elements 

Example; DECLARE FUNCT ENTRY RETURNS (7); 
5 com E NO LENGTH SPECIFIED FOR STRING. LENGTH ASSUMED TO BE maximum value 
5C012I S ERROR IN STRING LENGTH SPECIFICATION. IGNORED IS invalid element 

Example; DECLARE CHARA CHARACTER (STU) ; 
5C013I S ERROR IN PRECISION ATTRIBUTE. IGNORED IS invalid element 

Example: DECLARE VAR FIXED (XYZ); 
5C014I E VALUE OF ARRAY BOUND MUST NOT BE 0. ASSUMED TO BE 1. 
5C015I E VALUE OF ARRAY BOUND TOO HIGH. ASSUMED TO BE maximum value 
5C016I S ERROR IN DIMENSION ATTRIBUTE. IGNORED IS invalid element 

Example; DELCARE A (7 , 1 , J> ; 

5C017I E RIGHT PARENTHESIS MISSING. CORRESPONDING LEFT ONE IGNORED BEFORE declare_sta- 
tement item 
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5C018I S NESTING OF ATTRIBUTE FACTORIZATIONS TOO DEEP. DECLARATIONS FROM NESTING LEVEL 
9 ON IGNORED 

5C019I E INVALID ATTRIBUTE(S) IGNORED.. invalid attribute t, invalid attribute...] 

5C020I E SYNTACTICALLY ILLEGAL CHARACTERIS) IGNORED.- ignored character (s) 

Example: DECLARE PP FIXED $; 

5C021I S DECL, TOO LONG. ITEMS EXCEEDING LIMIT ARE IGNORED BEGINNING WITH declare Sta- 
teiPent item 

5C022I S NO NAME OR FACTORIZATION FOR LEVELNUMBER. . level number 

Example: DECLARE 1 STR, 2, 3 STRl; 
5C023I S NO INITIALIZATION WITH INITIAL ATTRIBUTE. 

Example: DECLARE VAR INITIAL STATIC; 

5C024I S LEVELNUMBER MUST NOT BE 0. ASSUMED TO BE 1. 

5C025I E STRINGLENGTH MUST NOT BE 0. ASSUMED TO BE maximum value 

SCO 2 61 E PRECISION TOO LARGE. SET TO 53. 

5C027I E SCALEFACTOR TOO GREAT. ASSUMED TO BE maximum value 

5C028I E STRINGLENGTH TOO GREAT. ASSUMED TO BE maximum value 

5C029I E LIST OF INITIALIZATIONS NOT CLOSED BY ) . PARENTHESIS INSERTED AT END OF 
STATEMENT. 

5C030I E NUMBER OF DIGITS IN PRECISION ATTRIBUTE MUST NOT BE 0. DEFAULT VALUE ASSUMED. 

5C0«43I S TOO MANY DIGITS SPECIFIED FOR PICTURE VARIABLE. DEFAULT VALUE IN SYMTAB 
ASSUMED FOR variable name. 

Explanation: The precision of the numeric-picture variable exceeds 15 or 16 
digits for decimal fixed or decimal float, respectively. This would lead to 
an error at execution time. In the symbol-table listing, the default value is 
printed. 

5C04UI S SYNTAX ERROR IN INITIALLIST. NO INITIALIZATION CF variable name 

Explanation: The INITIAL-list is composed of the following elements: con- 
stants, iteration- factors, left and right parentheses, and commas. Error 
number 44 will be issued if 

• the succession of these elements is incorrect, or 

• the constants or iteration- factors are incorrect. 

Examples of incorrect succession: 

1. INITIAL (1,2,) 

2. INITIAL (1, (2,3)) 

3. INITIAL (1,(10) (2,3)4) 

Examples of incorrect constants : 

1. 1013B 

2. 123E 

3. 1.21.2L 
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Examples of incorrect iteration- factors: 



5C045I 
5C046I 

5C01I7I 
5C0U8I 



5C0U9I 



1. INITIAL ((-3)0) 

2. INITIAL ((0) (1,2)) 

3. INITIAL (10(1,2)) 

Moreover, message number 44 will be issued, if there is an illegal character 
within the INITIAL-list, e.g., INITIAL (2*3). 

NESTING DEPTH EXCEEDS 8. NO INITIALIZATION OF variable name 



ITERATION FACTOR NOT ALLOWED FOR SCALAR VARIABLE. 
name 



NO INITIAL. OF variable 



ExamEle: DECLARE Z FIXED INITIAL ((3)4); 

ITERATION FACTOR GREATER THAN 32K. NO INITIALIZATION OF variable name 

WRONG DATA TYPE. NO INITIALIZATION OF variable name 

Explana ti on: This error message will be issued, if the type of a constant 
within the INITIAL-list is not compatible with the type of the variable to be 
initialized. 

Exam£le: DECLARE A DECIMAL FIXED INITIAL ('ABO; 

INITIAL VALUE IS NOT A LABEL CONST. WITHIN THE SCOPE OF LABEL VARIABLE. NO 
INITIAL. OF variable name 

Explanation: The label constant is internal to a procedure or begin block 
internal to the block in which the label- variable is declared. 

Example: P: PROCEDURE; 

DECLARE LAB LABEL INITIAL (L2); 



BEGIN; 

L2: END; 
END P; 

5C050I S MORE THAN ONE CONST. FOR SCALAR VARIABLE. NO INITIALIZATION OF variable name 

Example: DECLARE Y INITIAL {3E + 01, 33 E + 2); 

5C051I W TOO MANY CONSTANTS FOR ARRAY. EXCESS ONES IGNORED FOR array name 

5C052I S INITIALLIST TOO LONG. INITIAL ATTRIBUTE IGNORED FOR variable name 

5C053I T SYMBOL TABLE ERROR FOR INITIALIZED name 

Explanation: This message occurs only if a STATIC structure containing ele- 
ments with INITIAL attribute is multiply declared. 

5C054I E ERROR IN F-OPTION OF FILE filename 

5C055I E LEFT PARENTHESIS INSERTED IN FILE filename 

5C056I E ILLEGAL ELEMENT IGNORED IN FILE filename 

5C057I E RIGHT PARENTHESIS INSERTED IN FILE filename 

5C058I S ILLEGAL OSAGE OF REGIONAL OPTION. OPTION IGNORED IN FILE filename 
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5C059I W KEYED ATTRIBUTE INSERTED FOR DIRECT AND/OR INDEXED FILE filename 

1^2i§0§tion: Files with the attributes DIRECT and/or INDEXED must have the 
attribute KEYED. 

5C060I T KEYLENGTH SPECIFICATION MISSING IN FILE filename 

Explanation: KEYLENGTH must be specified in files having the KEYED attribute- 

5C061I T ERROR IN KEYLENGTH SPECIFICATION FOR FILE filename 

5C062I T ERROR IN BLOCKSIZE SPECIFICATION FOR FILE filename 

5C063I E ERROR IN BUFFERS OPTION. BUFFERS (1) ASSUMED FOR FILE filename 

5C064I E ERROR IN OFLTRACKS SPECIFICATION. OFL TRACKS IGNORED FOR FILE filename 

5C065I T ERROR IN MEDIUM OPTION FOR FILE filename 

5C066I T INVALID LOGICAL DEVICE NAME IN FILE filename 

Examgle: DECLARE FILE2 FILE INPUT ENVIRONMENT (MEDIUM (SYSRDR, 2540) . . . ) ; 
SYSRDR is an invalid logical unit (choice must be made between SYSIPT and SYS- 
nnn [nnn=001-222]) . 

5C067I T INVALID DEVICE TYPE SPECIFICATION IN FILE filename 

Exam£le: DECLARE FILE3 FILE- ., ENVIRONMENT (MEDIUM( , . . , 2020) ...),- 

5C068I T DEVICE TYPE OR FUNC, ATTR. CONFLICTS WITH LOG. DEVICE NAME IN FILE filename 

Example; DECLARE FILE4 FILE INPUT ENVIRONMENT (MEDIUM (SYSOOl, 1403)...); 
Input from Printer 14 03 impossible. 

5C069I T CONFLICTING ATTRIBUTES AND/OR OPTIONS IN FILE filename 

Exam£les: 1. DECLARE FILES FILE INPUT RECORD UPDATE .,.; 

2. DECLARE FILE6 FILE OUTPUT ENVIRONMENT (MEDIUM (SYS002, 1403) 
LEAVE NOLABEL F (81)); 

5C070I T INPUT, OUTPUT, OR UPDATE ATTRIBUTE MISSING IN FILE filename 

5C071I E DIRECT ATTRIBUTE INSERTED FOR REGIONAL FILE filename 

5C072I E NOLABEL OPTION INSERTED FOR UNBUFFERED TAPE FILE filename 

5C073I T ENVIRONMENT ATTRIBUTE MISSING IN FILE filename 

5C074I T MEDIUM OPTION MISSING IN FILE filename 

5C075I T BLOCKSIZE NOT DIVISIBLE BY RECORDSIZE IN FILE filename 

5C076I W RECORDSIZE OF RECORD NOT DIVISIBLE BY 8 IN FILE filename 

Explanation: The record size must be divisible by 8 if blocked records are to 
be transferred by a READ SET or LOCATE statement. 

5C077I W DIVISION OF BLOCKSIZE BY 8 DOES NOT YIELD REMAINDER OF 4 IN FILE filename 

§52i£LD§:£i20 * If the V option is used, the record size of records to be trans- 
ferred by a READ SET or LOCATE Statement must yield a remainder of 4 after 
division by 8. 

5C078I T BLOCKSIZE BEYOND DEVICE DEPENDENT LIMITS IN FILE filename 

5C079I T F, U, OR V OPTION MISSING IN FILE filename 
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5C080I T MORE ERROR (S) IN FILE filename 

Explanation: The maximum number of error messages issued for one file 
declaration is 7. If the file declaration contains more than 7 errors, this 
message is printed, 

5C081I E INVALID ATTRIBUTE IGNORED IN FILE filename 

5C08 2I E PRINT ATTRIBUTE ASSUMED FOR PRINTER AS PHYSICAL DEVICE IN FILE filename 

5C084I T ERROR IN EXTENT NUMBER SPECIFICATION FOR FILE filename 

5C085I E EXTENTNUMBER SET TO 3 IN DECLARATION OF FILE filename 

5C086I S INVALID DEVICE TYPE SPECIFIED FOR HIGHINDEX IN FILE filename 

Explanation: Only the device types 2311 and 2314 are allowed. 2321 may be 
specified if the device type in the corresponding MEDIUM option is also 2321. 

System Action: The invalid device type is used for execution. 

5C087I S NUMBER OF OFLTRACKS EXCEEDS DEVICE DEPENDENT LIMITS IN FILE filename 

Explanati on : The number n of overflow tracks specified in the OFLTRACKS 
option roust be within the following limits : 

< n < 8 for 2311 

< n < 18 for 2314 and 2321 

System Action: The value in error is used for execution, 

5C088I S KEYLOC BEYOND RECORDSIZE LIMITS IN FILE filename 

Explanation: The key location n specified in the KEYLOC option must be within 
the following limits: 

1 < n < record size - keylength + 1 

The message is issued if n > record size - keylength +1, If n =?= message 
5C092I is printed. 

System Action: The value in error is used for execution. 

5C089I S ADDBUFF AREA LESS THAN MINIMUM OR GREATER THAN MAXIMUM IN FILE filename 

Explanation: The number n of bytes specified in the ADDBUFF option must be 
within the following limits: 

64 + block size + keylength < n < 32K 

System Action: The value in error is used for execution, 

5C090I S RECORDSIZE NOT GREATER THAN KEYLENGTH IN FILE filename 

Explanation: For blocked records, the record size must be greater than the 
keylength. If KEYLOC is specified, this also applies for unblocked records. 

Sys te m Action: The value in error is used for execution, 

5C091I W RECORDSIZE EXCEEDS LIMIT FOR OVERFLOW RECORD IN FILE filename 

Exp la nation: The lengths n of the records on the overflow tracks are 
restricted as follows : 

n < 3605 - keylength - 10 bytes for 2311 
n < 7249 - keylength - 10 bytes for 2314 
n < 1984 - keylength - 10 bytes for 2321 
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5C092I E INDEXAREA, ADDBOFF, HIGHINDEX OR KEYLOC OPTICN IGNORED IN FILE filename 

SxBlanation: One of the options INDEXAREA. ADDBUFF, HIGHINDEX or KEYLOC is 
either not followed by a parenthesized specification or is followed by an 
invalid specification. 

5C093I 3 INDEXAREA LESS THAN HINIHUM OR GREATER THAN mAXIwuH IN FILE filenanie 

~^0^§D§tiQ"- "^^s number n of bytes specified in the INDEXAREA option must not 
exceed the following limits: 

3 + (key length +6) < n < 32K 

System Action; The value in error is used for execution, 
5C091H S MAX. NUMBER OF EXPL. DECLARED VARIABLES PER BLOCK REACHED WITH name 
5C095I E MORE THAN ONE INITIAL ATTRIBUTE FOR variable name 

System Action: Only the first INITIAL attribute is used, 
5C096I E MORE THAN ONE DIMENSION ATTRIBUTE FOR variable name 

System Action: Only the first dimension attribute is used. 
SCO 971 E MORE THAN ONE LEVELNUMBER FOR STRUCTURE ITEM Structure item name 

System Action: The first level number is used, 
5C098I E MORE THAN ONE PRECISION OR STRING LENGTH SPECIFIED FOR variable name 

Systen)_Action ; The first precision or length is used, 
5C099I E MORE THAN ONE PICTURE ATTRIBUTE SPECIFIED FOR variable name 

§Y§tem_Action: Only the first PICTURE attribute is used. 
5C100I E MORE THAN ONE BASE OR POINTER SPECIFIED FOR variable name 

Examgle: DECLARE NAME BASED(X) DECIMAL FIXED(7) BASEDCY); 

5C101I E STRUCT. NOT START. WITH LEVELNUMBER 1, ASS. TO BE MAJOR STRUCT. NAME IS struc- 
ture name 

Example; DECLARE 2A, 2B, 2C; A is assumed to be the major-structure name. 
5C102I E NON-FILETYPE ATTRIBUTES IGNORED FOR FILE filename 
5 CIO 3 1 E NON- APPLICABLE ATTRIBUTE(S) IGNORED FOR STRUCTURE structure name 

Examele: DECLARE 1 Al FIXEDr 2B, 2C ; 

5C104I S INVALID INITIALIZATION IGNORED FOR variable name 

Exglanation; Initialization with INITIAL-attribute is conflicting with type 
or attributes of the variable, 

Examgle; DECLARE E ENTRY INITIAL (SUBPRO); 

5C105I E ALIGNMENT PERFORMED FOR BITSTRING bitstring-variable name 

Explanation; Bit strings contained in structures and bitstring- arrays are 
aligned by the D-corapiler. 

5C106I E MORE THAN 12 DIFF. PARAMETERS TO BE PASSED TO OR FROM BLOCK NUMBER block 
number 
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5C107I 
5C108I 



Explanation; Number of parameters is limited to 12. 

E TOO MANY DIGITS SPECIFIED IN PREC. ATTR. DEFAULT VALUE ASSUMED FOR variable 
naire 

E NO SCALE ALLOWED WITH FLOAT OR BIN FIXED. DFLT. PRECIS. ASSUiXlED FOR variable 
name 

Explanation: A scale factor must not be specified within the precision attri- 
bute of BINARY FIXED or FLOAT variables. The whole precision attribute will 
be ignored and the default precision is assAimed for that variable. 



Examples : 

Illegal: 

BINARY FIXED (15,3) 
BINARY FIXED (31,0) 
DECIMAL FLOAT (3,2) 
DECIMAL FLOAT (6,0) 
BINARY FLOAT (53,8) 
BINARY FLOAT (53,0) 



Assumed: 

BINARY FIXED (15) 
BINARY FIXED (15) 
DECIMAL FLOAT (6) 
DECIMAL FLOAT (6) 
BINARY FLOAT (21) 
BINARY FLOAT (21) 



5C109I E ENTRY INTO EXT. PROC. IS OF TYPE EXTERNAL. INTERNAL ATTR. IGN. FOR entry name 

5 Clio I T MORE THAN 32K BYTES REQUIRED FOR ARRAY array name 

5C111I T POINTER AND/OR BASE IDENT, NOT OR INCORRECTLY DECL. FOR ARRAY array name 

Example; DECLARE U, BAS(IO) BASED (U) ; U is not a pointer. 

5C113I T REFERENCED VARIABLE OR RELATED BASE/POINTER INCORR. FOR ARRAY array name 

Example: DECLARE 1 A, 2 (B(10),C), X(10) DEFINED B; 

Defining on elements of structures is not allowed. 



5C115I 
5C116I 
5 CI 17 1 
5C118I 
5C119I 
5C120I 

5C121I 
5C122I 
5C123I 
5C124I 



E REPLICATION FACTOR OF ZERO IGNORED IN INITIAL LIST OF variable name 
E STRING CONSTANTS TRUNCATED ON RIGHT IN INITIAL LIST OF variable name 
E EXPONENTS TRUNCATED ON RIGHT IN INITIAL LIST OF variable name 
E FLOAT. CONSTANTS TRUNCATED ON RIGHT IN INITIAL LIST OF variable name 

ZERO ASSUMED FOR INVALID FLOAT. CONSTANTS IN INITIAL LIST OF variable name 



MAX, VALUE ASSUMED FOR INVALID FLOAT. CONSTANTS IN INITIAL LIST OF variable 
name 

STERLING CONSTANTS TRUNCATED ON RIGHT IN INITIAL LIST OF variable name 

BINARY FIXED CONSTANTS TRUNCATED ON RIGHT IN INITIAL LIST OF variable name 

DECIMAL FIXED CONSTANTS TRUNCATED ON RIGHT IN INITIAL LIST OF variable name 



E RESULT OF CONST. CONV. UNDEF. DUE TO SIZE ERROR. CHECK INITIAL LIST OF vari- 
able name 



5E001I T ILLEGAL CHARACTER IN LABEL PREFIX OR STATEMENT BEGINNING, 

Examples: 1. LBl: +B2: LB3 : ABC = 50; 

Second label is not an identifier. 

2. LAB: +BC = 50; 

Statement begins with an illegal character. 

System Action: The error statement is replaced by a dummy statement. 
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5E002I T STATEMENT TYPE CANNOT BE IDENTIFIED. 

Explanation: An identifier at statement beginning is neither a statement 
identifier nor followed by the assignment symbol =. 

Example: PUTT SKIP EDIT (B) (A) ; PUTT is not a statement identifier. 

Sys tem Action : The error statement is replaced by a dummy statement, 

5E003I T NESTING OF BLOCKS EXCEEDS 3 LEVELS. 

Explanation: Implementation restriction. The depth of nested blocks is 
restricted to 3 levels. The external procedijce is the first level. 

System Action: The flagged statement is replaced by the required number of 
END statements. The subsequent statements are ignored. 

5E00UI T NUMBER OF BLOCKS EXCEEDS 6 3. 

^jSHl§D^^iQf^ • Implementation restriction. The total number of blocks in. an 
external procedure {including the external procedure) must not exceed 63. 

System Acti qn : The flagged statement is replaced by the required number of 
END statements. The subsequent statements are ignored. 

User Response: Reduce number of blocks in one compilation by generating 
external procedures. 

5E005I T ILLEGAL CHARACTER FOUND IN IF-STATEMENT BEFORE *THEN' IS DETECTED. 
Example: IF A = 1; THEN GOTO LAB ; 
§Y§tem_Ac t ion : The incorrect IF statement is replaced by a dummy statement, 

5E006I T NO LABEL IS PERMITTED BEFORE AN ELSE-CLAUSE. 

Example: IF A = 1 THEN . . . ; LAB: ELSE B = 5; 

5E007I T ELSE FOLLOWED BY INVALID UNIT. 

Example: IF A = 1 THEN ...; ELSE 5 = B; where B is a correctly declared 
variable 

System Action: The invalid ELSE clause is replaced by a dummy statement. 

5E008i T DO-GROUP NESTING EXCEEDS 12 LEVELS, 

Explanation: Implementation restriction. The maximum depth of a nested set 
of DO statements (including repetitive specifications in GET or PUT state- 
ments) is 12. 

System Action: The flagged DO statement is replaced by a dummy statement and 
the following text is ignored. 

5E009I T INVALID END STATEMENT. 

55Ei§2§ti2D* "^^^^ keyword END is not followed by a semicolon or by the label 
of its associated PROCEDURE, BEGIN, or DO statement. 

Example: LAB: PROCEDURE; 
END LAS; 
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5E013I 



5E014I 



5E010I T LOGICAL END OF PROGRAM DETECTED BEFORE END OF SOURCE TEXT. 

Exp la nation; Text follows the logical end of the program. The programmer 
seems to have made an error in matching END statements with PROCEDURE, BEGIN, 
or DO statements. 

§Y§t§S!_^2£i20- ^11 text following the flagged statement is ignored, 
5E011I T MORE THAN ONE LABEL BEFORE PROCEDURE OR ENTRY STATEMENT. 

Explanation: PROCEDURE and ENTRY statements must have one and only one label. 
5E012I T NO LABEL BEFORE PROC. OR ENTRY STATEMENT. LABEL B INSERTED. 

Explanation; PROCEDURE and ENTRY statements must have one and only one label. 

System_ Action : The compiler inserts the label 'B:* before the flagged state- 
ment. This may cause further error messages (e.g., multiple declaration), 

T FIRST STMNT NOT PROCEDURE STMNT- FOLLOWING TEXT IGNORED. 

§Z§tem_Action ; Further error messages may result (e.g., 5E012I and 5E015I). 
T STATEMENT TOO LONG. STATEMENT TRUNCATED. 

Explanation; Internal buffer overflow. 

User Response; Subdivide statement and recompile. 
5E015I T END OF SOURCE MODULE FOUND BEFORE LOGICAL END OF PROGRAM, 

Explanation : Problem causing the err6r may be: 

1. Missing final semicolon. 

Example: LAB: PROCEDURE OPTIONS (MAIN) ; 

END 
/* 

2. Missing END statement(s) . 

Example: LAB: PROCEDURE OPTIONS (MAIN) ; 

DO I = 1 TO 5; 
END; 
/* 

5E016I T RIGHT PARENTHESIS MISSING IN THIS STATEMENT. 

Example: A(2,3,l = 15; where A is declared as a three-dimensional array, 

5E017I T END OF SOURCE MODULE FOUND IN PARENTHESIZED LIST. 

5E018I T ILLEGAL CHARACTERS IGNORED IN THE PROGRAM 

Explanation: Any of the characters listed below in hexadecimal notation are 
ignored unless they are included in a character string. In a program contain- 
ing such illegal characters, the compiler flags the first statement that is 
found to include one or more of these characters. 

the illegal characters are: 

B8 DA through DF 

BA through BF EA through EF 
CA through CF FA through FE 
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5E020I T ELEMENT IN PREFIX LIST IS NOT A LEGAL CONDITION NAME. 

Explanation; The prefix list contains either an illegal condition name or no 
condition name at all . 

Exareples: 1. ( ) : LA.B: statement; 

2. {ZERODIVIDE,+UNDERFLOW): LAB: Statement; 

3. (ZERODIDIvE, UNDERFLOW): LAB: statement; 
System Action: The entire prefix list is ignored. 

5E021I T NAME IN PREFIX LIST NOT FOLLOWED BY COMMA OR PARENTHESIS. 

ExamEles: 1. . (ZERODIVIDE UNDERFLOW): statement; 
2. { OVERFLOW'S- CONVERS ION) : statement; 

System Action; The entire prefix list is ignored, 
5E022I T CONFLICTING CONDITION NAMES IN PREFIX LIST. 

Example: (NOCONVERSION, CONVERSION) : statement; 

^Y§t§5!_^9ti9S • '^'^^ conflicting names are ignored. 

5E023I T COLON AFTER PREFIX LIST IS MISSING. 

5E025I T RIGHT PARENTHESIS IS MISSING IN DATA OR FORMAT LIST 

5E025I T MAIN PROCEDURE HAS INCORRECT OPTION LIST, 

??^El;3B§ti2D • F°^ ^he D-level compiler, the option list of a irain procedure is 
defined as 

MAIN[,ONSYSLOG] 

It roust be enclosed in parentheses immediately followed by a serricolon. The 
problem causing the error may be: 

1. Missing comma or right parenthesis. 
Example: TEST: PROCEDURE OPTIONS (MAIN; 

2. Element in list which is not an identifier. 
Examele: TEST: PROCEDURE OPTIONS (+AIN) ; 

3. Identifier in list which is neither MAIN nor ONSYSLOG. 
Example: TEST: PROCEDURE OPTIONS (MIAN) ; 

U. Option list not followed by semicolon. 

5E027I T NESTING OF ATTRIBUTES EXCEEDS 8 LEVELS. 

5E028I T INVALID DEFINED ATTRIBUTE IGNORED. 

5E029I T ILLEGAL FACTORIZATION OF FILE ATTRIBUTES. 

5E034I T TWO OR MORE IDENTICAL IDENTIFIERS IN ONE PARAMETER LIST, 

5E0U0I T FIRST ARGUMENT IN SUBSTR PSEUDO-VARIABLE IS NOT A STRING VAR. 

SE041I T MAJOR OR MINOR STRUCTURE IN IF STATEMENT. 
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5E042I T ARRAY IN ELEMENT-EXPRESSION OF IF-STATEMENT 

5E043I W NO DATA FORMAT ITEM IN FORMAT LIST. 

5E0ti4I T ARRAY DECLARATION INCORRECT. FIRST BOUND OF ARRAY IS ZERO. 

5E0U5I T EXTERNAL NAME(S) OF THIS PROGRAM LONGER THAN 8 CHARACTERS. 

Ex plana tion; See explanation of message 5E0U6I. 

5E046I E EXTERNAL NAME(S) OF THIS PROGRAM LONGER THAN 6 CHARACTERS. 

Explanation; Implementation restriction. The length of external identifiers 
must not exceed 6 characters. This also applies to names that are external by 
default such as filenames, names of external procedures, etc. If an identifi- 
er has 7 or 8 characters, the object program can still be executed but errors 
may possibly occur. If the external identifier is longer than 8 characters 
the compilation is terminated (message 5E045I is issued). The statement in 
error indicated in this message need not be the statement in which the error 
is detected. 

5E047I T TOO MANY IDENTIFIERS IN THIS STATEMENT. 

Use r Response; Subdivide statement and recompile. 

5E049I T POINTER AND/OR BASE IDENTIFIER NOT OR INCORRECTLY DECLARED, 

Exatngles: 1. DECLARE G CHARACTER (U) ; 

DECLARE K CHARACTER (U) BASED (G); 
K = 'TEST'; 
2. DECLARE P DECIMAL FLOAT POINTER; 
DECLARE A BASED (P) ; 
A = A+1; 

In both examples, the third statement is flagged. 

5E050I T ATTRIBUTE TABLE OVERFLOW. TOO MANY VARIABLES IN THIS STMNT. 

User Resgonsfe; For each element variable and for each structure element named 
in the statement, a table entry will be generated. 

Subdivide statement and recompile. 

5E051I T INVALID DEFINING 

Exa mp le; DECLARE 1 A, 

2 B DEFINED D, 
2 C; 
DECLARE D; 
B = 4; 

The third statement causes the error message. 

5E053I T OPERAND IN A GOTO STATEMENT IS NOT A LABEL. 

Explanation; The operand in a GOTO statement must always be a label constant 
or an element label variable. 

5E055I S 2ER0- REPLICATION FACTOR FOR STRING CONSTANT IGNORED. 

5E056I S STRING CONSTANT TOO LONG. TRUNCATED. 

Explanation; Implementation restriction. The length of bit-string constants 
is restricted to 6 4 bits; the length of character- string constants is 
restricted to 255 characters. 

System Action; Bit strings exceeding 64 bits and character strings exceeding 
255 characters are truncated on the right. 
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5E057I E EXPONENT TOO LONG. TRUNCATED. 

Exglanations Implementation restriction. The exponent subfield of a decimal 
floating point constant is restricted to 2 digits, and that of a binary float- 
ing point constant to 3 digits, 

Systeit! ?kction: The exponent is truncated on the right. 

5E058I E FLOATING-POINT CONSTANT TOO LONG. TRUNCATED. 

Explanation: Implementation restriction. The length of binary floating-point 
data is restricted to 53 bits; the length of decimal floating-point data is 
restricted to 16 digits- 

Sy stem Acti on: Decimal and binary floating-point constants exceeding 16 
digits or 53 bits, respectively, are truncated on the right, and the exponents 
are increased by the number of digits or bits truncated, 

5E059I E FLOATING-POINT CONSTANT TOO SMALL. SET TO ZERO. 

5E060I E FLOATING-POINT CONSTANT TOO LARGE. MAXIMUM VALUE ASSUMED. 

5E061I E STERLING CONSTANT TRUNCATED, 

Explanation; The sterling constant is converted to and stored as decimal 
fixed-poxnt pence = The converted constant must riOt exceed 15 significant 
digits . 

System Action: The converted decimal fixed- point pence number is truncated en 
the right, 

5E062I E BINARY FIXED-POINT CONSTANT TOO LONG. TRUNCATED. 

Explanation; Implementation restriction. The length of binary fixed-point 
numbers must not exceed 31 bits- 

§Y§tem_Actign: The constant is truncated on the right. 

5E063:i E DECIMAL FIXED-POINT CONSTANT TOO LONG. TRUNCATED. 

l?Ei§S§ti9D* Implementation restriction. The length of decimal fixed-point 
numbers must not exceed 15 digits. 

System Action; The constant is truncated on the right. 

5E064I E RESULT OF CONSTANT CONVERSION UNDEFINED DUE TO SIZE ERROR. 

Exp la nation: The number of significant digits resulting froir the constant 
conversion is greater than the precision specified for the target. 

Exarnele: DECLARE X FIXED BINARY CIO); 
X = 2.4<*4E5; 

5E065I T TOO MANY CONSTANTS IN THIS COMPILATION. 

Explanation: Internal buffer or constant-counter overflow. 

5E067I E INVALID CHARACTER STRING. ONE BLANK ASSUMED. 

Explanation: The apostrophe opening the character string is irr.mediately fol- 
lowed by the closing apostrophe. 

System Action: The compiler assumes the character string to consist of one 
blank. ^ ~ 

5E068I T QUALIFIED NAME NOT DECLARED. 
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Example: LAB: PROCEDURE OPTIONS (MAIN); 
STRUCT. SUBl = 50; 
END; 

5E069I T REFERENCED VARIABLE OR RELATED BASE/POINTER INCORRECT. 

Sxamgle: DECLARE A CHARACTER (3) BASED (P) ; 
A = 'XYZ* ; 

If P is not declared, the assignment statement causes the error 
message. 

5E070I E A ) HAS BEEN INSERTED IN ARGUMENT OR FORMAL PARAMETER LIST. 

Example: CALL DYNDUMP (A, B ; 

5E071I T UNSPECIFIED SYNTACTICAL ERROR. 

Example; DO A = ( B TO C BY D WHILE (E)); where A is a variable and B, C, D, 
E are valid expressions. The parentheses enclosing the sp^ecif ication of the 
DO statement are illegal. 

5E072I T INTERNAL BUFFER OVERFLOW. (PROBABLY TOO MANY PARENTHESES), 

User ..Response: Subdivide statement and recompile. 

5E07 3I E ONE OR MORE ) INSERTED TO- OBTAIN A VALID EXPRESSION. 

Examgle: DECLARE (A,B,C,D,E) DECIMAL FIXED; 
A = B** (C+D*E ; 

5E07m E ACTION FOR 5E073I MAY CAUSE ADDITIONAL ERROR MESSAGES. 

5E075I T 2ND OPERAND IN DISPLAY STATEMENT INVALID. 

Explanation: The second operand of the DISPLAY statement must be a character- 
string element variable enclosed in parentheses. 

5E076I T SHILLING FIELD OF STERLING CONSTANT GREATER THAN 19. 

5E077I T ERROR IN PARAMETER, OR SUBSCRIPT, OR ARGUMENT LIST. 

5E078I S ILLEGAL FILENAME OR LABEL IDENT. IN ON, SIGNAL OR REVERT STMT. 

5E079I T WHILE FOLLOWED BY INVALID EXPRESSION. 

5E080I T 1ST OPERAND IN DISPLAY STATEMENT INVALID. 

Expla na tion; The first operand in a DISPLAY statement must be an element 
expression enclosed in parentheses. 

5 EOS II T INVALID OR MISSING CONDITION NAME, 

Explanation; The keyword ON is not followed by a valid condition name and/or 
filename. 

Examples; 1. ON +ONVERSION GOTO LAB; 

2. ON CNVERSION GOTO LAB; 

3. ON ENDFILE GOTO LAB; (filename missing) 

tt, ON ENDPAGE( PRATE) GOTO LAB; (invalid filename) 

5E082I T INVALID OR MISSING OPERAND AFTER GOTO IN ON STATEMENT; 

Explanation; The keyword GOTO in an ON statement is not followed by an 
identifier, 

ExartjEles: 1. ON CONVERSION GOTO; 

2, ON CONVERSION GOTO +AE; 
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5E083I T ONSPECIFIED ERROR IN ON STATEMENT. 

Explanation: The ON statement has the following format: 

ON condition (SYSTEM; | ON-unit) 

The compiler detected that the ON-condition is neither followed by the keyword 
SYSTEM nor by a valid ON-unit. 

Example: ON CONVERSION +5; 

5E081H T INVALID CALL STATEMENT. 

Explanation; No identifier, especially no entry name, is following the key- 
word CALL. 

Examples : 1. CALL +AB; 
2 . CALL ; 

5E085I T ERROR IN CLOSE LIST. 

Explanation: The CLOSE statement has the following format: 

CLOSE FILE (filename) [, FILE (filename)] ...; 

Either the keyword CLOSE or one of the commas in the list is not followed by 

Exarnples: 1, CLOSE FLE (OUT); 

2. CLOSE (OUT) ; 

3. CLOSE FILE (OUT), (IN); 

5E086I T ERROR IN FILE OPTION 

5?EEi§:D§Lti2D* Syntax error. The file option consists of the keyword FILE fol- 
lowed by the file name enclosed in parentheses. 

Examples: 1, OPEN FILE (+-♦); 

2. OPEN FILE IN) ; 

3. CLOSE FILE (IN ; 

where IN is a valid file name, 

5E087I T ERROR IN OPEN LIST. 

Explanation; The OPEN statement has the following format: 

OPEN FILE (filename) options group [,FILE (filename) options group]...; 

Either the keyword OPEN or one of the commas in the list is not followed by 
the keyword FILE, 

Examples: 1. OPEN FLE (IN); 

2 . OPE N (IN); 

3. OPEN FILE (IN), (OUT); 

5E088I T WRONG FILE OPTION IN READ, WRITE, OR REWRITE STMNT. 

Explanation: The keyword READ, WRITE, or REWRITE is not followed by the key- 
word FILE. 

5E089I T INVALID OR MISSING OPERAND IN PAGESIZE OPTION. 

5E090I T NO SET OPTION IN LOCATE STATEMENT. 

l?£Ei§2§ti22 = 'r*^® file option in a LOCATE statement is not followed by the 
keyword SET, 
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Examgles: 1. LOCATE A FILE (OUT) ; 

2. LOCATE A FILE (OUT) SE (P); 



5E091I T liWALID OR MISSING OPERAND IN KEY OPTION, 

Explanation: Syntax error. The KEY option must consist of the keyword KEY 
followed by a parenthesized expression representing a character string. 

5E092I T INVALID FROM, FILE, OR INTO OPTION. 

Explanation; Syntax error. FROM, FILE, or INTO is not followed by a valid 
operand, or the operand is not enclosed in parentheses. 

Exanvgle: PUT FILE OUT EDIT (BUFFER) (A) ; 

5E093I T INVALID OR MISSING OPERAND IN SET, STRING-, OR KEYTO OPTION. 

Explanation; Syntax error. E.g., the SET option consists of the keyword SET 
followed by the name of a pointer variable enclosed in parentheses. 

Examples: 1. LOCATE A FILE (OUT) SET (Pi ; where Pi is a pointer variable. 
2. LOCATE A FILE (OUT) SET (1); 

5E094I T INVALID OR MISSING OPERAND IN KEYFROM OPTION. 

Explanation: The keyword KEYFROM must be followed by an element expression 
enclosed in parentheses. 

5E096I T ERROR IN FORMAT LIST 

l£^Ei3:S§.^i2B • "^^^ error may be caused by: 

1. Left parenthesis of one of the format lists is missing. 

2. A left parenthesis or one of the commas in thei list is neither followed by 
an iteration factor nor by a valid format item. 

3. An iteration factor in the list is neither followed by a valid format item 
nor by a format list. 

5E097I E MISSING ) INSERTED IN FORMAT LIST. 

5E098I T MISSING OR INVALID CONTROLVARIABLE IN DO- STATEMENT. 

Example; DO C(5) = 1 TO 7; 

The control variable C must not be subscripted. 

5E099I T INVALID LINE, COLUMN, OR X FORMAT ITEM. 

Explanation: Missing or invalid operand in a LINE, COLUMN, or X-format item. 

Examele: PUT SKIP EDIT (BUFFER) (X(5, A) ; 

In the above example, the right parenthesis enclosing the operand of the X- 
format item is missing. 

INVALID R FORMAT ITEM. 

Explanation: Missing or invalid operand in an R-format item. 

MISSING { IN E OR F FORMAT ITEM. 

MISSING INTEGER IN E OR F FORMAT ITEM. 

MISSING ) IN E OR F FORMAT ITEM. 

COMMA MISSING AFTER 1ST INTEGER IN E FORMAT ITEM. 

BUILT-IN FUNCTION AS ARGUMENT OF PSEUDO- VARIABLE. 



5E100I 


T 


5E101I 


T 


5E102I 


T 


5E103I 


T 


5E104I 


T 


5E105I 


T 
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5E108I T INVALID OPTION LIST IN READ OR WRITE STATEMENT. 



5E109I 



MAIN PROCEDURE MUST NOT RETURN AN EXPRESSION VALUE^ 



5E110I S CHARACTER OR BIT EXPRESSION IS TOO LONG. 

Exnlanation? The nurober of characters resulting from the evaluation of a 
character-string expression must not exceed 255. For bit-string expressions, 
the number of resulting bits must not exceed 64. 

5E111I T DATA, OPTION, OR FORMAT LIST CONTAINS INVALID ITEM(S). 

Examples: 1. PUT SKIP EDIT (BUFFER (A) ; 

Right parenthesis missing after BUFFER. 
2. PUT EDIT SKIP (BUFFER) (A); 

The keyword EDIT must immediately be followed by the data 
specification. 



5E112I T 

5E113I T 

5E114I S 

5E116I T 



c;:?'! 1 TT 



5E118I E 
5E119I T 
5E120I S 



:3iiiiiii 



TjavBLID DATA ELEMENT. 

INVALID REPETITIVE SPECIFICATION. 

ENTRYPOINT IN THIS STATEMENT INVALIDLY DECLARED. 

MISSING OR WRONG BASED VAR. OR FILE OPTION IN LOCATE STMNT. 

Explanation : Syntax error. The LOCATE statement has the following format: 

LOCATE based variable FILE (filename) SET (pointer variable) ; 

The based variable must be unsubscripted and must not be a minor structure or 
an element of a structure. 

Exameles: 1, LOCATE +1 FILE (OUT) SET (Pi) ; 
2, LOCATE Al (OUT) SET (PI); 

INVALID EXPRESSION. 

Explanation: The error may be caused by: 

1, Missing operand. 

2. Two infix operators not separated by operand, 

WARNING FOR INCORRECT PREFIX IN ENTRY STATEMENT. 

TOO MANY ENTRY POINTS AND/OR ON CONDITIONS IN BLOCK. 

ILLEGAL NULL STATEMENT IN ON- UNIT. 

Explanation: The null on-unit must not be specified for the conditions CONV- 
ERSION, ENDFILE, and KEY. 



END OF INVALIDLY NESTED DO GROUP. 



NESTING EXCEEDS 12 LEVELS, 



5E122I S 
5E123I S 



Explanation: Implementation restriction. The maximum depth of a nested set 
of DO statements (including repetitive specifications in GET or PUT state- 
ments) is 12- This message is issued as a follow-up to message 5E008I. 

System Action: The flagged END statement is replaced by a dummy statement. 

ILLEGAL FILENAME IN ON CONDITION. 

ILLEGAL LABEL IDENTIFIER IN ON UNIT. 

ExanjEle: DECLARE C DECIMAL FIXED; 
ON CONVERSION GOTO C; 
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5E124I E REVERT STATEMENT WITHOUT CORRESPONDING ON STATEMENT. 



5E126I E INCORRECT NUMBER OF ARGUMENTS. 

ExarQEle: B = SUBSTR(A, 1 1) ; 

Due to a missing comma in the argument list, the compiler recognizes only two 

arguments . 

5E127I E OPTIONS MAY NOT BE SPEC, FOR SUB PROCEDURES. OPTIONS IGNORED. 

5E128I T BUILT-IN FUNCTION NAME IN INCORRECT CONTEXT. 

Explanation: A built-in function name has explicitly been declared with the 
BUILTIN attribute, but is used in a non-function-reference context, 

Examjgle: DECLARE ABS BUILTIN; 
ABS = ABS + 1; 

Note: Built-in functions without arguments or which have been declared con- 
textually only are not concerned. 

5E129I S CONVERSION OF ARITH. DATA TO BIT STRING YIELDS RESULT GT 31. 

5E130I T INVALID KEY. 

5E131I T MORE THAN 65534 VARIABLES AND/OR CONSTANTS. 

Explanation: An internal overflow of the variable and constant counter of the 
compiler occurred. 

5E132I T STACK OVERFLOW. (IF-NEST TOO DEEP). 

Explanation: Implementation restriction: The maximum number of IF statements 
in a nest is 100. 

5E133I T PROBABLY BAD IF-NEST. 

5E13UI T ELSE IMMEDIATELY FOLLOWS IF. 

5E135I T ELSE IMMEDIATELY FOLLOWS ANOTHER ELSE. 

5 El 37 1 T ILLEGAL STATEMENT USED AS UNIT IN AN IF STATEMENT. 

Ex§rogles: 1. IF element expression THEN f^ORMAT (format-list) ; 

2. IF element expression THEN unit-1 ELSE FORMAT (format-list); 

The FORMAT statement is not permitted as unit in an IF statement. 

ELSE WITHOUT CORRESPONDING IF, 

INCORRECT SPECIFICATION OF CONSTANT ARGUMENT. 

TOO MANY STRUCTURES IN STRUCTURE ASSIGNMENT. 

NUMBER OF INTERMEDIATE RESULTS IS TOO BIG. STACK OVERFLOW, 

NON-IDENTICAL STRUCTURING IN STRUCTURE ASSIGNMENT. 

ARRAY USED IN INCORRECT CONTEXT. 

STRUCTURE USED IN INCORRECT CONTEXT. 

INVALID CONVERSION OR ILLEGAL COMBINATION OF DATA TYPES. 

Exa mp le: P = A; where A is a character string and P is a pointer variable, 

5E147I T NON-IDENTICAL NUMBER OF ARRAY ELEMENTS IN ARRAY-ASSIGNMENT, 



5E138I 


T 


5E11*0I 


S 


5E1U1I 


T 


5Em2l 


T 


5Em3l 


T 


5E14UI 


T 


5E145I 


T 


5E146I 


T 
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5E148I T UNPERMITTED ASSIGNMENT TO FUNCTION VALUE, 

Explanation; The left side of an assignment statement is a built-in function 
which is neither a STRING built-in function nor a pseudo variable. 

5Em9I S NUMBER OF ARGUMENTS IS GREATER THAN TWELVE. 

5E150I T TOO MANY REPETITIVE SPECIFICATIONS. 

Explanation: implementation restriction. The number of iteration specifica- 
tions must not exceed 50. 

Examgle: DO I = 1 TO 2, 2 TO 3, 3 TO a, ..., 51 TO 52; 

System^Action: The flagged DO statement is replaced by a dummy statement and 
the following text is ignored. 

5E152I T PROCESSING OF STATEMENT TERMINATED. (TABLE OVERFLOW). 

Explanation: An internal table overflow occurred during the processing of a 
DO statement. 

Since the DO statement will be deleted from the text string, there will be a 
surplus END statement in the source program. 

Us er_ Response: Subdivide statement and recompile, 

5E153^I T POINTER AS ELEMENT OF DATA LIST = 

5E154I W POSSIBLE ERROR IN FORMAT ITEM IP USED FOR OUTPUT. 

5E155I S INCORRECT ARGUMENT IN BUILT-IN FUNCTION OR PSEUDO-VARIABLE. 

Exainple: DECLARE (A,B) CHARACTER (2) ; 
B = SUBSTR(A,5,4) ; 

Since A and B are only two characters long, the arguments 5 and U in the argu 
ment list are invalid. 

5E0156I S INVALID NUMBER OF DIMENSIONS. 

Example: A (2 3,1) = 15; where A is declared as a three-diirensional array. 
The error is caused by a missing comm^ between the integers 2 and 3. 

5E157I W ERROR IF USED FOR OUTPUT, 

5E158I T ENTRY NAME OR LABEL ON LEFT SIDE OF ASSIGNMENT STATEMENT, 

Example: LAB: N = 3; DO LAB = A TO B; where A and B are valid expressions, 

5E159I T R FORMAT ITEM IN ITERATION LIST AT DEPTH GREATER THAN TWO. 

5E160I T STATEMENT TOO LONG. STATEMENT DELETED. 

Explanation: Internal buffer overflow. 
2§§L_B§§E2D§§ • Subdivide statement and recompile. 

SE161I T TOO MANY IDENTIFIERS IN PROGRAM. 

5E162I S CONTROL ITEMS NOT ALLOWED FOR THIS STATEMENT. 

5E163I T NO LABEL DESIGNATOR IN REMOTE FORMAT ITEM. 

SEieuI E LABEL CONST. IN R FORMAT ITEM NOT INTERNAL TO CRRNT BLOCK. 

Explanation: The R format item and the specified FORMAT statement must be 
internal to the same block, 
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5E165I S NO POINTER VARIABLE IN SET OPTION. 

5E166I S INCORRECT RECORD VARIABLE. 

5E167I W RECORD VARIABLE ON WRONG BOUNDARY. 

Exglanation : The variable is not on a double-vjord boundary. An error may 
occur if^later a READ statement with the SET option is issued, and a similar 
variable is used. 

5E168I S RECORD VARIABLE ON WRONG BOUNDARY, 

5E169I S RECORD VARIABLE LENGTH NOT IN ACCORDANCE WITH RECORDSIZE, 

5E170I S INCORRECT VARIABLE IN STRING OPTION. 

5E171I T INCORRECT NAME IN FILE OPTION. 

Explanation; File name not or incorrectly declared. 
5E172I S STATEMENT NOT IN ACCORDANCE WITH FILE DECLARATION. 
5E173I T INCORRECT ITEM IN DATA LIST. 

5E17UI T NO STRING VARIABLE IN SUBSTR PSEUDO- VARIABLE. 
5E175I T FORMAT LIST TOO LONG. 

Explanation: Internal buffer overflow. 
5E176I S FORMAT STATEMENT NOT PRECEDED BY LABEL, STATEMENT DELETED, 

Explanation; A FORMAT statement must be preceded by at least one label. 

5E177I T TOO MANY FORMAT LABELS IN PROGRAM. 

Explanation; Implementation restriction. The number of labels preceding FOR- 
MAT statements in one program is restricted to 127. 

5E178I T NESTING OF ITERATION LIST IN FORMAT LIST TOO DEEP. 

5E179I S REMOTE FORMAT ITEM IN FORMAT STATEMENT. STATEMENT DELETED. 

Explanation; A FORMAT statement cannot contain an R format item. 
System Action: The error statement is deleted from the text string, 

5E180I S INCORRECT A,B FORMAT ITEM IN GET STATEMENT, 

5E181I S VIOLATION OF FORMAT ITEM RESTRICTION. 

5E182I W MOD (LENGTH OF RECORD VARIABLE, 8) IS UNEQUAL TC FOUR. 

Explanation: If the V option is used, the record size of records to be trans- 
ferred by a READ SET or LOCATE Statement must yield a remainder of U after 
division by 8. 

5E183I S INCORRECT VARIABLE IN REPLY OPTION. 

5E184I S WRONG VARIABLE IN SET OR KEYTO OPTION. 

5E186I T TOO MANY REPETITIVE SPECIFICATIONS IN DATA SPECIFICATION. 

5E187I S LENGTH OF RECORD VARIABLE GREATER THAN MAXBLCCKSIZE. 

5E218I S ILLEGAL EXPRESSION IN ASSIGNMENT STATEMENT. 
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5E219I S MORE THAN TWELVE PARAMETERS IN PROGEDURE/ENTRY STATEMENT. 

§Y§tSl!i_^2ti2Q* '^'^^ parameter list is truncated on the right, 

5E228I E CHARACTER STRING IN DISPLAY STATEMENT LONGER THAN 80 BYTES. 

5E229I E EVALUATION OF OPTIM. SUBSCR. YIELDS DISPLACEM. GREATER 32K 

^52l§.0§Ltion: At least one subscripted variable in this statement is outside 
the declared bound of the array. 

Example : The semantically wrong statement A(I) = A(I+35000): where A is de- 
clared as A(10), will cause this diagnostic message. This error is only 
detected if OPT is specified. 

5E230I W IMPLEMENTATION DEFINED SUBROUTINE. 

Explanation: This warning message will appear for each statement using one of 
the facilities DYNDUMP, OVERLAY, IJKTROK, IJKTRCF, IJKEXHC. 

5E231I E TOO MANY ARGUMENTS FOR IJKEXHC IN ONE BLOCK. 

5E232I E INVALID ARGUMENT(S) FOR EXHIBIT CHANGED IGNORED. 

5E233I E UNPERMITTED VALUE OF CONSTANT SUBSCRIPT(S) . 

Explanation; Constant subscript (s) too large. The absolute value of the dis- 
placement to the origin of the array is greater than 32767. 

5E23m E NO SCALE FACTOR GIVEN IN BUILT-IN-FUNCT. 

Explanation; Concerning the built in functions ADD, MULTIPLY, DIVIDE for 
fixed-scale arguments. 

5E235I S INTERMED. RESULT IN ADD-FUNCT. TOO LONG. STATEMT. IGNORED 

Explanation: Length of necessary working space (resulting frcir precision and 
scale of the arguments) greater than hardware defined limits (only for fixed 
scale arguments) . 

5E236I S INTERMED. SCALE-FACT, EXCEEDS PERMITTED RANGE 

Explanation: The intermediate scale factor in the built-in- functions ADD, 
MULTIPLY, or DIVIDE is greater than 127 or less than -128 (only for fixed- 
scale arguments) . 

5E237I S EVEN PRECISION HERE NOT ALLOWED. CHOICE ODD TARGET PRECISION. 

5E238I E TIME/DATE/OR NULL ASSUMED TO NAME PL/I BUILT-IN-FUNCTION 

S52i§D§ti2D' Builtin functions without arguments should be explicit ely de- 
clared with the BUILTIN attribute. 

5E239I E UNKNOWN FUNCTION UK SUBROUTINE. ATTR. ENTRY ASSUMED 

5?£Ei§53ti9D • Entry names must be explicitly declared with the attribute 
ENTRY. 

5G01I PROGRAM BLOCK GREATER THAN 32K. COMPILATION TERMINATED. 

5G02I SOURCE PROGRAM TOO LONG. COMPILATION TERMINATED. 

5G03I STATIC STORAGE OVERFLOW. COMPILATION TERMINATED. 

5 GO 4 I AUTOMATIC STORAGE OVERFLOW. COMPILATION TERMINATED. 

5G05I MORE THAN 256 ESID NUMBERS NECESSARY. COMPIIATICN TERMINATED. 
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5G06I MORE THAN 65,534 VARIABLES AND/OR CONSTANTS, COMPILATION TERMINATED. 

5G07I POSSIBLE RECURSIVE USE OF EXTERNAL PROCEDURE. COMPILATION TERMINATED. 

5W01I SUCCESSFUL COMPILATION. 

5W02I COMPILATION IN ERROR. 
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Appendix G. Object-Time Diagnostic Messages 



INote: For a discussion of the program- 
checkout facilities of the compiler, refer 
I -ho the se'^tion Pro"r3ni— Checkout F3cilitiss. 

T'he format of object-time diagnostic mes- 
sages is as follows: 

5L00I ccqqqqqq aaaaaa ERROR nnnn 

5L00I is a prefix to identify the message 
as a PL/I object- time message. 



is raised and no ON-unit is currently being 
executed for this condition. 



cc 



are two hexadecimal digits identi- 
fying the message, (see the message 



cEqqqqq are six hexadecimal digits qualify- 
ing the message code with the 
address of a file, if applicable^. 
Otherwise six zeros. 

aaaaaa are six hexadecimal digits specify- 
ing the address where th« error was 
detected. If the error was 
detected in a library routine, 
aaaaaa is the address of the 
instruction that follows the call 
of the routine in the PL/I object 
program. 

nnnn is the number of the source state- 
ment that caused the error. This 
nunftber is printed only if STMT was 
specified in the PL/I PROCESS card. 
If STMT was not specified or when 
the compiler cannot determine the 
statement that caused the error, 
nnnn is set to 0000. 

The messages are -listed below by message 
code number (cc above). 

Notes : 

1. For errors not raising an ON- condition 
(other than ERROR) , a message is 
printed for the specific error and the 
ERROR condition is raised. This app- 
lies to all errors with a message code 
higher than 10. 

2. If SYSLST is not yet opened (for 
example, because of insufficient 
storage available for DSA) , some of the 
messages tray be printed only on the 
console. 



LIST OF MESSAGE CODES 

PL/ION-Condition Comments 

These object-time diagnostic messages are 
issued only if an enabled PL/I ON-condition 



01 


OVERFLOW 


02 


UNDERFLOW 


03 


ZERODIVIDE 


04 


FIXED OVERFLOW 


05 


SIZE 


06 


CONVERSION 


09 


ERROR 


OA 


ENDFIIE 


OC 


TRANSMIT 


OD 


KEY 


OE 


RECORD 



Only the last four conditions use the file- 
name qualification. 

With indexed-sequential files the END- 
FILE condition will also be raised if a key 
higher than the last one on the file is 
requested. If the ENDFILE condition is not 
enabled for the file, the message 80 - NO 
RECORD FOUND - will be issued. 



Ha rdware_Interrupts 

Severe programming errors might lead to 
program-check hardware interrupts during 
the execution of a PL/I program. These 
possible interrupts are identified by the 
following codes: 

11 Operation Exception 

12 Privileged-Operation Exception 

13 Execute Exception 

14 Protection Exception 

15 Addressing Exception 

16 Specification Exception 

17 Data Exception 

IE Significance Exception 

Each of these exceptions is briefly dis- 
cussed below. 



ii=.9E??§t^55_l^^§P!^i2Ii- When an operation 
code is not assigned or the assigned opera- 
tion is not available on the particular 
model, an operation exception is reco- 
gnized. The operation is suppressed. 

The instruction-length code is 1, 2, or 3. 

12 Privileged^Operation Exce pti on. When a 
privileged instruction is encountered in 
the problem state, a privileged-operation 
exception is recognized. The operation is 
suppressed. 

The instruction- length code is 1 or 2. 
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13 Execute Exception. When the subject 
instruction of EXECUTE is another EXECUTE, 
an execute exception is recognized. The 
operation is suppressed. 

The instruction-length code is 2. 

m Protection Exception. When the key of 
an instruction halfword or an operand in 
storage does not match the protection key 
in the PSW, a protection exception is 
recognized. 

The operation is suppressed on a store 
violation, except in the case of STORE MUL- 
TIPLE, READ, DIRECT, TEST, AND SET, and 
variable-length operations, which are 
terminated. 

Except for EXECUTE, which is suppressed, 
the operation is terminated on a fetch 
violation. 

The instruction- length code is 0, 2, or 3. 

15 Addressing Exception. When an address 
specifies any part of "'data, an instruction, 
or a control word outside the available 
storage for the pariiicular installation, an 
addressing exception is recognized. 

In most cases, the operation is ter- 
minated for an invalid data address. Data 
in storage remain unchanged, except when 
designated by valid addresses. In a few 
cases, an invalid data address causes the 
instruction to be suppressed - AND (NI) , 
EXCLUSIVE OR (XI), OR (01), MOVE (MVI), 
CONVERT TO DECIMAL, DIAGNOSE, EXECUTE, and 
certain store operations (ST, STC, STH, 
STD, and STS). The operation is suppressed 
for an invalid instruction address. 

The instruction-length code normally is 1, 
2 or 3; but may be in the case of a data 
address. 

16 Specification Exception. A specifica- 
tion exception is recognized when: 

1. A data, instruction, or control- word 
address does not specify an integral 
boundary for the unit of information, 

2. The Ri field of an instruction speci- 
fies an odd register address for a pair 
of general registers that contains a 
64-bit operand. 

3. A floating-point register address other 
than 0, 2, 4, or 6 is specified. 

^ . The multiplier or divisor in decimal 
arithmetic exceeds 15 digits and sign. 

5. The first operand field is shorter than 
or equal to the second operand field in 
decimal multiplication or division. 



7. 



The block address specified in SET 
STORAGE KEY or INSERT STORAGE KEY has 
the four low-order bits not all zero, 

A PSW with a nonzero protection key is 
encountered when protection is not 
installed. 



The operation is suppressed. The 
instruction-length code is 1, 2, or 3. 



17 Data Exception . 
recognized when: 



A data exception is 



1. The sign or digit codes of operands in 
decimal arithmetic or editing opera- 
tions or in CONVERT TO BINARY are 
incorrect. 

2. Fields in decimal arithmetic overlap 
incorrectly. 

3. The decimal multiplicand has too many 
high-order significant digits- 

The operation is terminated. The 
instruction-length code is 2 or 3. 

IE Significance Exception. When the result 
of a floating-point addition or subtraction 
has an all-zero fraction, a significance 
exception is recognized. 

The operation is completed. The inter- 
ruption may be masked by PSW bit 39. The 
manner in which the operation is completed 
is determined by the mask bit* 

The instruction-length code is 1 or 2. 

Housekeeping Errors 

21 STORAGE OVERFLOW 

There is not sufficient storage avail- 
able for dynamic storage allocation. 

22 INVALID LABEL 

The label variable in a GOTO statement 
does not contain a valid label. 

23 SECOND CALL OF MAIN 

A procedure with the option MAIN is 
called by a PL/I program. 

2 a PARAMETER NOT ON DOUBLE -WORD BOUNDARY 
Procedure expecting double-precision 
floating-point variable as parameter 
has been passed single-precision value. 

25 INVALID SIGN CHARACTER 

Incorrect character for sign position 
of PICTURE data containing T, I, or R 
in specification. 

Mathematical ..and Arithmetical Subrouti nes 
(Short Arguments) 

30 X LT IN SQRT(X) 
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31 ABSCX) GE (2**18) *K IN SIN(X) 
OR COS(X) (K=PI) OR SIND(X) OR 
COSD(X) (K=180) 

32 ABS(X) GE (2**18)K IN TAN(X) 
(K=PI) OR TAND(X) (K=180) 



-» O TT 



■ Klr»Tt-r Ti t 



Jo A "iUU NEAR oX wiaUiiiixCx'x X Xvi 'L'i\vi\A. 

TAND(X) 



) or 



34 Y=X=0 IN ATAN(YfX) 

35 X GR 174. 6 IN SINHCX) OR COSH(X) 

36 X GR 174.6 IN EXP(X) 

37 X GR 1 IN ATANH(X) 

38 X LE IN LOG(X) OR L0G2 (X) OR LOGIO (X) 
OR X LE AND Y NOT FIXED POINT {P, 0) 
IN EXPRESSION X**Y 

39 X=0, Y LE IN X**Y 
3A X-0, N=0 IN X**N 

Mgt-heniatic al and Arithmetical Subroutines 
(Long Argunients) 

40 X LT IN SQRT(X) 

41 ABS(X) GE (2**50)*K IN SIN(X) OR COS(X) 

(K=PI) OR SIND(X) OR COSD(X) (K=180) 

42 ABS(X) GE (2**50) *K IN TAN(X) (K=PI) OR 
TAND(X) (K=180) 

4 3 X TOO NEAR SINGULARITY IN TAN(X) OR 
TAND(X) 

44 Y=X=0 IN ATAN(Y,X) 

45 X GR 174.6 IN SINH(X) OR COSH(X) 

46 X GR 174.6 IN EXP(X) 

47 X GR 1 IN ATANH(X) 

4 8 X LE IN LOG(X) OR L0G2(X) OR LOGIC (X) 
OR X LE AND Y NOT FIXED POINT (P,0) 
IN EXPRESSION X**Y 



ii n V— f» \T 
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4A X=0, N=0 IN X**N 
other Built-in Functions 

50 Y=0 IN MOD(X,Y) 
Binary fixed arguments 

51 Y=0 IN MOD(X,Y) 
Decimal fixed arguments 

52 Y=0 OR 

ABS(X/Y) GT 7.2*10**75 IN MOD(X,Y) 
Short floating-point arguments 



53 Y=0 OR 

ABS(X/Y) GT 7.2*10**75 IN MOD(X,Y) 
Long floating-point arguments 

54 MOD(X»Y) GET ABS(Y) 

Short floating-point arguments 

_»_> t'lv^uvAjX/ "Jii rtJ:3 0vx/ 

Long floating-point arguments 

MOD for floating-point argnments will 
be calculated as 

a=X/Y; b=Y*a; MOD(X,Y)=X-b 

If the exponent of X is so high that 
X+Y has the same value as X, then MOD ( 
X,Y)=0; message 54 or 55 will be 
generated in such a case, 

Input/Output Er ror s 

61 FORMAT ERROR 

Illegal combination of data list item 
and format list item, 

62 END OF STRING 

^ 4-4- ^:imT^.4- 4-i^ -v^ia/^ r^ir tj>- -l 4- £i 'Wl£i^7*-^r^/^ 4- Vi£i 

specified string in a GET EDIT or PUT 
EDIT statement with the STRING option. 

63 ILLEGAL USE OF CONTROL FORMAT OR OPTION 
An invalid PAGE, SKIP, LINE, or COLUMN 
format is specified for a file. 

64 ILLEGAL USE OF STREAM FILE 
Attempt to execute a disallowed GET 
EDIT or PUT EDIT Statement for a STREAM 
file. 

This error message may also occur if a 
program processes file labels, but the 
job-control LBLTYP card has been 
omitted in the job- control deck for the 
program. 
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ILLEGAL USE OF CONSECUTIVE BUFFERED 

FILE 

Attempt to execute a disallowed READ, 

WRITE, REWRITE, or LOCATE statement for 

a CONSECUTIVE BUFFERED file. 

This error message may also occur if a 
program processes file labels, but the 
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omitted in the job- control deck for the 
program. 

ILLEGAL USE OF CONSECUTIVE UNBUFFERED 
FILE 

Attempt to execute a disallowed READ, 
WRITE, or REWRITE Statement for a CON- 
SECUTIVE UNBUFFERED file. 

This error message may also occur if a 
program processes file labels, but the 
job-control LBLTYP card has been 
omitted in the job- control deck for the 
program. 
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67 ILLEGAL USE OF REGIONAL FILE 

Attempt to execute a disallowed READ, 
WRITE, or REWRITE Statement for a 
REGIONAL file. 



This error message may also occur if a 
program processes file labels, but the 
job-control LBLTYP card has been 
omitted in the job-control deck for the 
program. 

69 PAGE SIZE OPTION FOR NON-PRINT FILE 

6A ILLEGAL USE OF INDEXED SEQUENTIAL FILE 
Attempt to execute an invalid READ, 
WRITE, or REWRITE Statement for an 
INDEXED SEQUENTIAL file. 

6B ILLEGAL USE OF INDEXED DIRECT FILE 
Attempt to execute an invalid READ, 
WRITE, or REWRITE Statement for an 
INDEXED DIRECT file. 

This error message may also occur if a 
program processes file labels, but the 
job-control LBLTYP card has been 
omitted in the job-control deck for the 
program, 

6C INPUT DATA ELEMENT TOO LONG 

Attempt to read an element of excessive 
length in a GET LIST statement. 

6D TOO MANY CONCURRENT I/O ERRORS FOR 
STACK SIZE 

Indicates that more than three files 
have WLR and/or TRANSMIT errors being 
handled at the same time. 

6E FILE IN ERROR NOT IN STACK 

Indicates that a file with WLR or TRAN- 
SMIT error flagged in the DTF appendage 
is not in the error file stack. 
This message can also occur if the 
LBLTYP card has been omitted, thereby 
causing label data to overlay and set 
the appropriate bit in the DTF 
appendage . 

6F ILLEGAL USE OF STREAM FILE 

Attempt to execute a disallowed GET 
LIST or PUT LIST statement for a STREAM 
file. 

70 ERROR DURING POSITIONING OF INDEXED 
SEQUENTIAL INPUT FILE 

An error has occurred during the posi- 
tioning to the record key specified in 
the KEY option of a READ statement. 

71 ERROR DURING INITIALIZATION OF INDEXED 
SEQUENTIAL OUTPUT FILE 

The cylinder index area is not large 
enough to accommodate all entries 
required to index each cylinder speci- 
fied for the prime data area. 



72 ERROR DURING INITIALIZATION OF INDEXED 
SEQUENTIAL OUTPUT FILE 
The master index area is not large 
enough to accommodate all entries 
required to index each track of the 
cylinder index. 



7E END OF STRING 

Attempt to read or write beyond the 
specified string in a GET LIST or PUT 
LIST statement with the STRING option. 

If the ERROR condition is raised as a 
result of System action for the KEY condi- 
tion, one of the following messages may be 
printed to give a more specific description 
of the error that caused the KEY condition 
to be raised. 

80 NO RECORD FOUND 

The record to be retrieved by a READ 
KEY from an INDEXED file has not been 
found in the data file, 

81 OVERFLOW AREA FULL 

There is no more space available in the 
overflow areaCs) for the record to be 
added to an INDEXED DIRECT file by a 
XgRITE KEYFROM Statement. 

8 2 PRIME DATA AREA FULL 

The prime data area has been filled 
while creating or extending an INDEXED 
SEQUENTIAL file by a WRITE KEYFROM 
statement. 

83 DUPLICATE RECORD 

The record being added by a WRITE KEY- 
FROM STATEMENT to an INDEXED SEQUENTIAL 
or DIRECT file has a duplicate record 
key of another record in the file. 

84 SEQUENCE CHECK 

The record being written by a WRITE 
KEYFROM statement to an INDEXED SEQUEN- 
TIAL file is not in the sequential 
order required, 

87 FORMAT ERROR IN INPUT 

a) Delimiter is neither blank nor comma 

b) Character B is missing in external 
format of a bit string 

c) External format of data item is 
incompatible with internal declara- 
tion; for example: 

r T ^ 

I External | Internal | 
|. ^ 1 

I Character string | Bit string | 
J. + 1 

I String data | Numeric, E, | 
I I F- format | 
L X J 
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Symbols used: M = Use of this statement is mandatory 

O = For I/O statements: Use of this statement format is optional 
For ON conditions: This condition moy occur 

* = Note that GET/PUT STRING is not on I/O statement and may be used without 
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B - Optional for unblocked files. The default value for blocked files is n= 1. 
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Appendix J. Default Attributes of Coded Arithmetic Variables 



DECLARED ATTRIBUTES 


DEFAULT ATTRIBUTES 


DECIMAL FIXED 

DECIMAL FLOAT 

BINARY FIXED 

BINARY FLOAT 

DECIMAL 

BINARY 

FIXED 

FLOAT 

None - initial character 1 - N 

None ~ g!I others 


(5,0) 

u\ 
\"/ 

(15) 

(21) 

FLOAT (6) 

FLOAT (21) 

DECIMAL (5,0) 

DECIMAL (6) 

BINARY FIXED (15) 

DECI.V.AL FLOAT (6) 
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Appendix K. Restrictions to The PL/I Subset Language 



ALIGNED_gr_ONALIGNED 

Must not be specified for minor- structure 
names. 



Ar ithmet ic Consta nts 

Any embedded blanks in arithmetic constants 
will be deleted from the number string and 
no error message will be given. However, 
embedded blanks in repetition-factor fields 
of PICTURE items are not deleted. 



Arrays 

The maximum number of arrays in a source 
module is 32. 

Arrays_of_Structures 

Arrays of structures are not implemented. 

Attribute Factorization 

The maximum attribute factorization depth 
is 8. 

ginary JFixed-Point Data 

Binary fixed-point numbers may have a 
length between 1 and 31 bits. This also 
applies to all intermediate results in 
binary fixed-point form. 

Binary Floating-Point Data 

Binary floating-point data may have a 
length between 1 and 53 bits. 

Bit Strings 

Bit strings may have a length between 1 and 
64 bits. The default alignment attribute 
is not implemented; bit strings are aligned 
by the D-Compiler. A warning message is 
given if a bit string associated with the 
default alignment attribute occurs within a 
structure. 

Blanks 

Blanks embedded in arithmetic constants 
will be deleted (see also Arithmetic 

Blanks between operators will also be 
deleted. E.g., X * * Y; will be inter- 
preted as X**y. Similarly, 'XXX' 'YYY* 
will be interpreted as • XXX' 'YYY', result- 
ing in a character-string value of XXX'YYY. 



Blocks (of Program) 

The size of any internal or external pro- 
gram block (exclusive of data) is 
restricted to 32K. The size of an external 
block plus all of its internal blocks 
(exclusive of data) must not exceed 64K. 



The depth of nested blocks is restricted 
to 3. The external procedure counts as 
depth 1. 

The total number of blocks in an extern- 
al procedure (including the external proce- 
dure) must not exceed 63. 



Blgcksize_Options 

The block length must be at least 1 byte 
(18 bytes for magnetic tape files) and must 
not exceed 32,767 bytes. The device types 
and corresponding maximum block lengths are 
as follows : 



2540 
2540 
1442 
1442 
2520 
2520 
2501 
1403 

1403 
1404 

1404 
1443 

1443 
1445 

1445 
2400 
2400 
2311 
2311 
2311 
2314 
2314 
2314 
2321 
2321 
2321 



(CTLASA, CTL360) 

(CTLASA, CTL360) 

(CTLASA, CTL360) 

(PRINT attribute or CTLASA or 

CTL360) 

(no PRINT attribute) 

(PRINT attribute or CTLASA or 

CTL360) 

(no PRINT attribute) 

(PRINT attribute or CTLASA or 

CTL360) 

(no PRINT attribute) 

(PRINT attribute or CTLASA or 

CTL360) 

(no PRINT attribute) 

(no PRINT attribute) 

(PRINT attribute) 

(no key, no PRINT attribute) 

(PRINT attribute) 

(including key) 

(no key, no PRINT attribute) 

(PRINT attribute) 

(including key) 

(no key, no PRINT attribute) 

(PRINT attribute) 

(including key) 



80 
81 
80 
81 
80 
81 
80 
133 

132 
133 

132 
145 

144 
114 

113 
32,767 

145 
3625 

145 
3605 
7294 

145 
7249 
2000 

145 
1984 



The block size option V must include the 
control fields for the blocks and records. 

Only f ixed'-length unblocked records are 
permitted for STREAM files. 
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The block size options V and U and the F 
option with the record size option are per- 
mitted for magnetic tape files and disk 
files only. 



Built- in_Functions 

String arguments must not be used in the 
ROUND built-in function. 

Bit arguments must not be used with the 
UNSPEC built-in function. 



Decimal Figed-Pgint_Data 

Decimal fixed- point numbers may have a 
length between 1 and 15 digits^ This also 
applies to all intermediate results in 
decimal fixed-point form. 



Decimal jJoating-Po int Dat a 

Decimal floating-point numbers may have a 
length between 1 and 16 digits. 

DECLARE Statement 



Character Strings 

Character strings may have a length between 

1 anri OS"^- 



Compatibility with OS F PL/I 

1. A GOTO statement which branches direct- 
ly into an iterative DO loop will not 
be diagnosed as an error by the D Com- 
piler, although such a statement is not 
allowed in the language, and is flagged 
as illegal by the F Compiler. 

2. Certain statements are not recognized 
by the F compiler (see DYNDUMP^ 
IJKEXHC, . . . in this Appendix) . 

3. The I/O ENVIRONMENT attributes are not 
recognized by the F Compiler, 

Refer also to Appendix B. Upward Compa- 

ti^iiitY ill the publication IBM. System/360 
DOS/TOS_PL /I Subset Reference Manual, ""order 
No, GC28-8202. 



Arithmetic to bit string: 

The scale factor must be less than the 

precision. 

Bit string to arithmetic: 

The maximum length of the bit string to be 

converted is 31, 

Data _ Storage 

Static - internal: 

The static storage for any external proce- 
dure (excluding external data) must be less 
than 6aK, 

Automatic: 

The automatic storage area per block must 

be less than 6t»K. 

Data aggregates : 

Each individual data aggregate must be less 

than 32K, 



The length of a DECLARE statement is unre- 
stricted; however, the length of one 
declaration-unit appearing in a DECLARE 
statement is restricted to 

• 136 syntactical elements, if lOK bytes 
are available to the compiler, and to 

• 2000 syntactical elements, if 46K bytes 
are available to the compiler. 

One declaration-unit is deliiriited by 

• the keyword DECLARE and a semicolon, or 

• the keyword DECLARE and a first- level 
comma, or 

• two first-level commas, or 

• a first-level comma and a semicolon. 

Each parenthesis, identifier, comma, 
attribute, and constant is counted as one 
syntactical element. A character- string 
constant in an INITIAL- list counts as two 
syntactical elements. Consider the follow- 
ing example: 

DECLARE (X FIXED, D FLOAT) STATIC, 

(A INITIAL (7), B(10)) EXTERNAL, 
NAME CHARACTER (4) INITIAL 
CABCD*); 

The above DECLARE statement consists of 
three, declaration-units, the first of which 
contains 8, the second 13, and the third 10 
syntactical elements. 

DEFINED Attribute 

A bit class variable must not be a DEFINED 
item. The attributes for the DEFINED item 
and the base identifier will not be checked 
to determine whether they correspond to the 
rules for overlay defining. 

Dimension Attribute 

The maximum number of dimensions is 3. 
Each bound must be an unsigned integer less 
than 32,768. The dimension attribute may 
be factored. 
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DISPLAY^Stateirent 

The result in the message expression in the 
DISPLAY statement must not exceed 80 chara- 
cters. If the REPLY option is used, the 
message must be followed by the EOB (End of 
Block) condition by pressing the appropri- 
ate keys. For an example see Appendix L. 

Programming Examples, "Using The Console 
For Communications". 



29_Statement 

The number of iteration specifications in a 
DO nest must not exceed 50. 

The maximum depth of a nested set of DO 
statements is 12. For details on repeti- 
tive specification see GET Statement. 

D YNDUMPj;__I JKEXHC , IJKTRON, IJKTROF, OVERLAY 
Names 






The names DYNDUMP, IJKEXHC, IJKTRCN, IJK- 
TROF, and OVERLAY are not recognized by the 
OS PL/I compiler. Consequently, the CALL 
statement referring to one of these names 
will result in an unresolved external 
reference from the linkage editor under the 
OS PL/I compiler. Onder the D-level com- 
piler, a warning message is issued for each 
statement using one of these names. 

END Statem en t 

If a label follows the END statement, it 
must be the label of the nearest unmatched 
PROCEDURE, BEGIN, or DO Statement. If a 
BEGIN or DO statement is preceded by more 
than one label, only the one closest to the 
statement identifier may be used with the 
END statement. 

The exponent subfield for decimal and 
binary floating-point constants is 
restricted to 3 digit positions for binary 
and 2 digits for decimal constants. 

?il§§_l3D^uf fered) 

For unbuffered files the RECORD condition 
will not be raised for records of incorrect 
length, because for the implementation of 
unbuffered files the system work files have 
been used (compiler enters the DTFSD para- 
meter TYPEFLE=WORK in the DTF table). 



Format constants: 

The format constants must be such that w, 
d, s, and p are decimal integer constants. 
Only p may be signed (positive or nega- 
tive). The A, X, LINE, and COLUMN field 
widths must be less than 256. The B field 
width must be less than 65. 
The E and F field width must be less than 
33. This width includes the sign for out- 
put fields even when they are positive, 
i.e., written as a blank. A SKIP must be 
less than 4. 

The exponent subfield for input data 
described by the E format specification is 
limited to 2 digit positions. 
The exponent subfield for output data 
described by the E format specification is 
always written with 2 digit positions. 



GET Statement 

The replication factor in a format list in 
GET or PUT statements may range between 1 
and 255. 

The depth of nested replication factors 
in a format list of GET or PUT statements 
is restricted to 5. If the format list 
contains a remote format item that is con- 
tained in a replication nest, it must not 
be at a depth greater than 2. 

The depth of a nested set of repetitive 
specifications as well as the total number 
of repetitive specifications in GET and PUT 
statements are restricted to 11. 



Identifiers 

The length of EXTERNAL identifiers must not 
exceed 6 characters. This also applies to 
names that are external by default, such as 
file names, names of external procedures, 
etc. 

II!_ Nesting 

The maximum number of IF statements in a 
nest is 100. 

Irriplicit_Declarations 

The identifiers DATE, NULL, and TIME should 
always be declared explicitly. If they are 
not explicitly declared a warning message 
is issued, and the BUILTIN attribute is 

assumed. 



FgRMAT_Statement 

Replication factors: 

The replication factor in a FORMAT state- 
ment may range between 1 and 255. 
The depth of nested replication factors in 
a format list of a FORMAT statement is 
limited to 2. 



INITTAL_Attrifcute 

The length of the INITIAL-list for a 
character-string array is restricted by the 
following formula: 

NC * LE + 14 * NF < NI 
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wnere 

NC = the number of constants in the 
INITI?^L-list 

LE = the length of one array element 

NF = the number of iteration factors 

NI = 1500 (if lOK are available to the 
conapiler) 
18000 (if 46K are available to the 
compiler) 

Consider the following example: 

DECLARE CH(IO) CHARACTER (250) INITIAL 
((3) (2) 'A', '8% (2)'C','D','E','F', 
•G','H'); 

The INITIAL-list in the above DECLARE 
statement contains eight constants and one 
iteration factor. String repetition fac- 
tors (as in (2) 'A* and (2)'C') are not 
counted. The length of one array element 
is 250. 

Application of the above foruiula yields 
a result of 201U which is in error if NI - 
1500. 



KEY Condition 



Not e: The above restrictions are applic- 
able only if the source program is coirpiled 
on a 16K system. The restrictions are 
eased considerably with the availability cf 
additional core storage. 

External names : 

The number of external naires must not 
exceed 255. Mames of external structures 
count as two names. This restriction is 
independent of the size of the available 
background program area. 



Note: The number 255 includes the naires of 
all library subroutines used by this 
external procedure. 

Total number of names : 

The total number of distinct internal and 



e'^'^t e'*^'^i 



ll 3 



xn a source ^iOyiaui uiust:. not 
This restriction is inde- 



pendent of the size of the available 
background 

Nestin g I/O Statements 

While an I/O statement is active, no other 
I/O statement must be activated (GET and 
PUT STRING are considered I/O statements in 
this connection). Thus, in the following 
example the second PUT statement is not 
allowed since it is 'nested' in the first 
one. 



The KEY condition will not be raised for 
REGIONAL files if an attempt is made to add 
a duplicate key by a WRITE statement. 



PUT FILE (X) EDIT (FUNCT (PARI, PAR2, . . . . ) 
(format list) ; 



Labels 

The total number of labels for all remote 
FORMAT statements in an external procedure 
must not exceed 127. This restriction is 
independent of the size of the available 
background program area- 

Since environmental information is 
assigned to a label variable during assign- 
ment, a static label variable must be 
initialized each time a procedure is 
activated. 



FUNCT: PROCEDURE (PARAl, PARA2, ) 

RETURNS (CHAR(120)); 
DCL Y CHAR (120) ; 



PUT STRING (Y) EDIT (data list) (format 
list) ; 



RETURN (Y) ; 
END FUNCT; 



UJ.O U i./ \J 



ON Statement 



The statement PUT LIST ( NULL) ; - where NULL 
is declared as the built-in function - will 
not be diagnosed as an error, but will be 
executed giving unpredictable output data. 

Names 

Internal names: 

The maximum number of names in all DECLARE 
statements of a program block is 3048. The 
maximum number of names given all its 
attributes by default is 3048. 



If the condition of the ON statement is 
CONVERSION, ENDFILE, or KEY, the action 
must not be the null statement. A prefix 
is not allowed in an ON statement, 

ON ENDFILE must not be specified with 
default files. When a program uses an 
implicit file declaration, such as GET FILE 
LIST (A,B,C); it is not possible to use ON 
ENDFILE (SYSIN). Therefore, when the END- 
FILE condition is raised, a message occurs, 
and the job is cancelled. 
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When a key error occurs in a WRITE sta- 
tement, the KEY condition is raised during 
execution of the current statement or the 
next I/O operation. 

The standard system action for FIXEDO- 
VERFLOW is coirment and raise the ERROR 
condition. 



PAGESIZE_gption 

The default condition is the size specified 
by the line count of the system. 



The number of distinct parameters of a pro- 
cedure must not exceed 12. The same para- 
meter appearing in a number of parameter 
lists of the same procedure (one PROCEDURE 
statement and several ENTRY statements, 
each with parameter lists) is considered as 
only one parameter. 



The PL/I Subset language does not have 
the attributes REDUCIBLE, IRREDUCIBLE, 
NORMAL, and ABNORMAL. Therefore, the user 
should familiarize himself with these items 
if he wishes to run programs written in the 
PL/I Subset language under OS control. For 
details on these attributes see the SRL 
publication IBM S ys tem/360, Operat ing Sys- 
tgn!,_PL/I(F) Language^Reference Manual, 
Order No. GC28-8201. 

PROCEDURE Statement 

The OPTIONS attribute permits an options 
list, the form of which is (MAIN [, 
0NSYSL0G3). The MAIN option specifies this 
procedure to be the initial procedure. The 
ONSYSLOG option specifies that all output 
as a result of action taken due to an ON 
condition is to be printed on the device 
assigned to SYSLOG. If both options are 
used, they must appear in the order given 
above. Procedures declared with the 
OPTIONS attribute cannot be called from 
other procedures. 



Entry name parameters must be explicitly Put Statement 
declared with the ENTRY attribute. 

Refer to GET Statement. 
PICTURE_Attribute 

A PICTURE specification must have at least 
one PICTURE character other than M, V, K, 
or G. Arithmetic pictures must not have 
more than 32 characters excluding M, V, K, 
and G. PICTURE character strings must not 
have more than 255 characters. A PICTURE 
character preceded by the replication fac- 
tor k is considered as k PICTURE 
characters- 



If a qualified name is truncated on the 
right, the remaining part of the qualified 
name m.ust be unique. For example, in the 
structure 



DECLARE 



PICTURE_Data 

Data declared with the PICTURE attribute 
must not have more than 15 digit-characters 
for numeric fixed- point data and 16 digit- 
characters for the mantissa and two for the 
exponent of numeric floating-point data. 

Pictures with the fill character * pre- 
ceded or followed by one of the characters 
+, -, S, or $ cause these characters to be 
replaced by * when the variable has a value 
of zero. Similarly, CR or DB are replaced 
by **. 

The picture character B is implemented 
as a conditional insertion character when 
used in conjunction with a drifting 
character. 

Procedure Default Condition 

The default condition for all procedures 
excluding built-in functions and library 
subroutines is IRREDUCIBLE. The default 
condition for all data is ABNORMAL in the 
DOS/TOS PL/I compiler. 



1 ATR, 
2 Al, 
3 Bl, 
3 B2, 
U Dl, 
U D2, 
2 A2, 
3 Bl, 
4 D3, 
4 D4, 
3 B3; 



the qualification ATR,B1.D3 is not allowed 
since ATR.Bl is not unique. The correct 
qualification would be ATR.A2.B1.D3. Ambi- 
guous names may not be flagged by the com- 
piler, and the code produced for such ambi- 
guous references is unpredictable. 

Repetition Factor 

A repetition factor must be an unsigned 
decimal integer. Its length is restricted 
to three digits. Its value must not exceed 
255. The two examples below are in error: 

DECLARE A PICTURE •(OOIO)X'; 
DECLARE B PICTURE ' (260)X'; 

No embedded blanks are allowed in the 
repetition factor. E.g. DECLARE C PICTURE 
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' (1 2)9'; is invalid. However, preceding 
or following blanks are allowed, as e.g. in 
DECLARE D PICTURE" ( U)X'; 



This includes the major-structure naitie, 
minor-structure name(s), and structure- 
element names. 



ocaxe rdccur 



Declaration of a scale factor is permitted 
only with decimal fixed-point data. It may 
range between and 15 and must be 
unsigned. 

Statetiients 

The total number of identifiers, constants, 
and delimiters (excluding insignificant 
blanks and comments) contained in a state- 
ment must not exceed 230. 

The number of different identifiers and 
constants (excluding constants not con- 
tained in an expression) is limited to 90 
for each statement. 

Note: The above restrictions are applic- 
able only if the program is compiled on a 
16K system. Each additional tiK available 
to the compiler allows an equivalent 
xncrease. 



Structure_Declarations 

The maximum logical depth of a structure is 
8. The maximum level number is 255. The 
number of names in a structure is 
restricted to 62, if lOK are available to 
the compiler (766 if ii6K are available). 



Structures J^level numbers) 

Any embedded blanks in level numbers will 
be deleted from the number string during 
compilation and no error message will be 
given. Level numbers may only be factored 
for elements of a structure, i.e., if fac- 
torization occurs in a structure declara- 
tion, the corresponding item.s are reco- 
gnized as structure elements. 

For example, in the declaration 

DCL 1 A, 

2(B,C,D), 
J \rj ,r fKjj ; 

B, C, D, E, F and G will all be assumed to 
be elements of structure A, and will be 
assigned the logical level 2. 

In order to obtain the structure 



DCL 1 



A, 

2 B, 



2 C, 

2 D, 
3 E, 
3 F, 
3 G; 

the declaration of D must be removed from 
tne factorization brackets. HI 
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® 



® 



® 



©I 



mutt wwm^BmM mtmrn ^Kiii> i 

2 HODB BINART(31)FIIED, 

a SIC 



f 




,*«;, 



PDT EDIT (•HODH»,«HIH«,'SEC«,«HOLL»,I) 
(SKIP, X (3) ,» (U) ,X (2) ,1 (3) ,1(2) ,i (3) , 
X(2) ,i(U) ,SKIP,F(6),F(5),F(5) ,F(6)); 



DECL&BE 1 X, 
2 AH CH&lt&CTEB (2) , 
2 IB CHIBACTEB (2) , 
2 AS CHABACTEB (2) , 
2 AHI CHABACTEBt3) , 

.s,»if|„i4# 




13 *tf i _ 

HOOa 1 BIH FTXYD (31), 

STBIHG(X)=TIHE; 

Y= '000011110000111VB 

H =nNSPEC(AH ) ; 

H= H & Y; 



nNts i * 

bi=sdbstr1;h,i,8) ; 
i b2=s0bstb(h,9,8 ) ; 

H0D?1= B2 +B1 ♦ 1010B 

■ ■ r, - 

timk 

# 








Figure 70, Conversion of Numbers in 
Character Form to Binary 
Numbers 



Conversion of Numbers in Character Form 
Into Binary Numbers 

The example in Figure 70 (encircled numbers 
are used for reference purposes only) shows 
how numbers in character form may be con- 
verted into binary numbers. For this pur- 
pose the time is used. 



Note, however, that the example shows 
machine-dependent programming and was cho- 
sen for illustration purposes only. 



The current time is obtained with the 
TIME built-in function ® which returns a 
character string of length nine, in the 
form h hm mss ttt , where: 

hh is the current hour of the day 
mm is the number of minutes 
ss is the number of seconds 
ttt is the number of milliseconds in 
machine-dependent increments 



Through the use of the STRING pseudo- 
variable the time (nine characters) is 
assigned piece by piece to the elements of 
X Q) (the lengths of the pieces being 
determined by the lengths of the elements 
in X), 

Take, for example, the time 



AM AMI 










^M^ i^^* 










162319080 


(4P 


M. , 23 minutM, 


19 seconds. 


and 


AK AS 


80 milliSBCondi) 







To convert from character to binary, the 
UNSPEC built-in function is used which 
returns a bit string that is the internal 
representation of a given value. Thus, the 
characters '1* and '6' would be represented 
as 



■lOOOl and M||p^ 



>1 and flPllO 
zona porrion zona portion 



Appendix L, Programming Examples 143 



To eliminate the zone portion of the 
characters, a mask is used ® and "anded" 
with the binary representation of the 
characters •!* and '6* (D : 



1111000111110110 



0000000100000110 
1 6 



Although the first byte of H now would 
contain binary one and the second binary 
siX:, the value of H would not be sixteen. 
To obtain an actual value of binary six- 
teen, the following is done: 



The SDBSTR built-in function is used to 
(a) extract the first eight bits of H 
(which would be ' 00000001') which are 
asisigned to Bl © and (b) extract the 
second eight bits ('00000110') which are 

(t\ ThoTi 4-1-10 xralno r^f R1 



I is multiplied by ten (which would yield a 
I value of ten) and the value of B2 (six) is 
I added (giving a total of sixteen). 



The result (g) must have a precision of 

binary multiplication ( (g) ^^^ ^^ ^ # if 
truncation is to be avoided = 



The method that is used to convert the 
hours is also used to convert the minutes, 
seconds, and milliseconds. The results are 
returned to the invoking procedurewhich 
prints them in the following form al) : 



HOUR 


MIN 


SEC 


MULL 


16 


33 


8 


960 


HOUR 


MIN 


SEC 


MULL 


16 


33 


9 


80 


HOUR 


MIN 


SEC 


MULL 


16 


33 


9 


220 


HOUR 


MIN 


SEC 


MULL 


16 


33 


9 


360 


unnp 


MTN 


civn 


mnl 1 



IHH 



Storing And Retrieving Statistical Data 

The example in Figure 71 (encircled numbers 
are used for reference purposes only) shows 



how volumes of statistical data that are 
too large to fit in core storage may be 
stored on disk and retrieved. 



// JOB STATLAB BEGIN OF JOB 

// ASSGW SYS009,X'29l' LOGICAL DEVICE ADDRESS IS 

* ASSIGNED TO PHYSICAL DEVICE (SEE ENV ATTRIBUTE) 
// DLBL STATLI,'LAB 6 DATA FILE',0,SD 

* STATLI = FILENAME USED IN PROGRAM 

* 'LAB 6 DATA FILE'=IDENTIFICATION OF DATA SET ON DISK 

* MEANS THAT THE FILE MAY BE OVERWRITTEN ANY TIME 

* SD INDICATES A SEQUENTIAL DISK FILE 
// EXTENT SYS009,PLID03, 1,0, 1800,40 

« SYS009 = LOGICAL ADDRESS OF EXTENT (SEE ENV ATTRIBUTE) 

* PLID03 = SERIAL NUMBER OF VOLUME TO WHICH EXTENT BELONGS 
« 1 INDICATES A DATA AREA 

* = EXTENT SEQUENCE NUMBER 

* 1800 = RELATIVE TRACK NUMBER CTRACK OF CYLINDER 1,801 

* 40 = NUMBER OF TRACKS THAT MAY BE USED 
// ASSGN SYS010,X'29l' 

// DLBL STATLA 'LAB 6 DATA FILE',0,SD 

// EXTENT SYS010,PL1D03, 1,0, 1800,40 

// OPTION LINK, LIST, SYM, ERRS, 60C,N0DECK,LISTX, DUMP 

// EXEC PL/I EXECUTION IS INITIATED 



DECLABE 1 I, 

2 XX(10) FLOIT BINABY (21), 
2 11(10) FLOAT BIHABY (21) | 



wmmnmm 



® 



(5) I IBITE FILE tSTATLI) FHOB (X) ; 



DO I = 1 TO 500; 
DO J = 1 TO 10; 




BEAD PILE (STATLA) IHTO (X) ; 
POT EDIT (X) (SKIP,20 F(a,0)) ; 




Figure 71. Storing And Retrieving statistical Data 



Appendix L- Programming Examples 145 



The program creates 5000 values @ 
which are stored on disk in groups of 10 
values each ( Q) and (3) ) . For this pur- 
pose a nested DO-group is used . 



The same data is then retrieved again 
from disk ® and printed in the form shown 
in Fiaure 72 i5j 
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Figure 72. Program Output of ST?IT 
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Creating And Retrieving a REGIONAL(l) File 

The program shown in Figure 73 (encircled 
numbers are used for reference purposes 
only) shows how a REGIONAL (1) file (|) may 
be created and retrieved from disk. 
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@ 




Job Control Stofements 
to Clear And 
Preformat Disk Area 



(Di 



Bt 82 
000 



Ct €2 









// JOB CLEAH 

// ASSGN SYS01 1,X«291« 

// DLBL OOUT,' CLASS', 000 >^ 

// EXTENT SYS011,PLID03,1,0,1500,5 ( 

// EXEC CLRDSK ' 

CLEAP DISK UTILITY 

LTILITY CONTROL CASES 

// UCL B= (K = 0,D = 080) ,X«4C« -ON 

// END 

IC«I LlSOf H - 

D&Ti LllfGfS * 080 

FILL CHARACTER - X'40' 

OtIT?ST PAM8BTI8 - 11 
ISSOflSB 9&tI881SBS 

01?IC2 TTP2 • 231t 
3£Cul(D3/TtAC& - 25 

IlfSHf BB I.0IS1 

SBC, HO, CI C2 

000 000 000 150 

BND 0? aOB 



// JOS BBaXOIL 

// O^iri.09 l.iiiftyBfa,i«;£Si;^«sss^60Ct 

// XSSSIf SIS01t,X*2f1* 

// DLBt CLASS, *H./I CLASS <.0$0«M 

// EXTXJiT SXSOI1,BI»lM$,t*i*tSM,S 

// iSS«» STS012*l»29t« 



FTEST: FIOCICCBB OrtlOHS^ttmi 

DECLARE CLASS FILZ C13TPDT DIRECT RECORD EhVIRONHENT (REGIONAL (1) 
F(eO) MEDIUR(SYSC11,23n)) KEYED; 

DECIDE* cus^i Ttm zmm%, 

DECLARE X CHARACTER (80) ; 
DECLAT»E I?JEC FICTUBE '(8)9'; 
OFBIt lltt |CI.A$$)| 

IREC=0; 

DO I « 1 f$ 10; 

WRITE FILE (CLASS) FROH (X) KSYFROH (IHEC) ; 

I11C»I*1C*IS 

»bb: 

CLOSB FlLi (CLASS) t 

TREC=0: 
POT Slip J 

opm fits (ctASSi) i 

DO I « I to 30; 

READ FILE (CLASSI) INTO (X) KEY (IREC) ; 
FOt IBI7 |t#Il«C^ <i (201 «ff 10^01 1 1 

Bid; 

Ct5Sl fZiB (CLAiiili 



Figure 73, Creating And Retrieving a REGIONAL (1) File 



148 



Before a REGIONAL (1) file can be 
created, the extents used by the file must 
be Preformatted by the DOS Clear Utility 
program (5) , which creates dummy records 
that contain a string filled with user- 
defined characters (3) - Only when the disk 
area preformatted, can the REGIONAL (1) file 
actually be created with the OUTPUT attri- 
bute d) , 



Each record in the file has a length of 
80 characters (® and ©), The key © 
which must be declared as a numeric- 
character variable with the attributes 
PICTURE* (8)9* is not contained in the reco- 
rd; it is not written on disk, but only 
indicates the relative number of the record 
in the file. The first record in a 
REGIONAL (1) file always has the relative 
record number ( (t) and (8) ) . The key 
used to identify the record on disk must be 
specified in the KEYFROM option (9) of the 
WRITE statement, or in the KEY option d^ 
of the READ statement. 



Printed, the records of the program 
shown in Figure 73 would look as shown in 
Figure 7U. 



123456789 
123U56789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 
123456789 



0123456789 

4123456789 

8123456789 

12123456789 

16123456789 

20123456789 

24123456789 

28123456789 

0123456789 

4123456789 

8123456789 

12123456789 

16123456789 

20123456789 

24123456789 

28123456789 



u 



Figure 74. Program Output of FTEST 
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Creating and Updating a Sequential 
Disk File 

The three programs shown in Figures 75 
through 77 (encircled numbers are used for 
reference purposes only) will create a 
file, update the file^ and punch the file 
back onto cards* It is a sequential file« 
The input is also sequential. 

The prograiri shown in Figure 75 creates e 
sequential disk file @ whose records are 
80 bytes long. The input for this file is 
furnished by presorted cards (2) . The 
records on the cards are just read (3) and 
written onto disk ® as they are. 

In the program shown in Figure 76 the 
data on disk created in the first program 
is updated @ , Input for any updates^ is 
furnished by other pre-sorted cards Q) . 

The information that is processed con- 
cerns college students,, their credit hours, 
grade points, etc. (5) , The updates 
reflect changes during a semester. 

The update process is as follows: Stu- 
dent identification (ID) on card records 
(§) are compared (D with student ID on 
disk records. If a disk record ID is 
smaller than the corresponding card ID, a 



new disk record is read in © , (7) . If the 
ID numbers are equal, the disk record is 
updated depending on the code of the card 
file record. The codes may be one of the 
following: 



R -- concerns only reaular hours_ and grade 
point changes ( \^ , 'v2^ , ^^^ ' 

F — coji^erns^nly total hours attempted 

N - 

P -- concerns probation ( [17) , ^ 
A - 



- concerns credit hours ( (14) , (15 

6^) 



19)) 



- cori^erns^nly ^tempt to change hours 
( qL9j , ^29 , {2y ) 



G — concerns Jiours±owards graduation 



)urs ±0 
( (22) , (23) , (g) ) 



When updated, the record is written back 
onto disk^ 125^ . ID errors (26^ and data 
errors ^7) ^re signalled by^'^rinting them 
out. The third program (shown in Figure 
77) reads the data on disk ((1) 'and (2)) 
and punches them, as they are (§) , into 
cards ® . 



// JOB CDHBDILD 

// DLBL IJSYS10, 'DATA-FILE' 

// EXTENT SYS010,?LID03, 1,0, 1500,250 

// &SSGN SYS010,X'291' 

// OPTION LIHK, SIM, LIST, ERBS,60C,NODECK,LISTI 

// EXEC PL/I 



® 

(D 

® 
® 



DECLARE IJSYS10 FILE ODTPDT BECOPD BUFFERED 

ENVIIIONHENT (MEDIUM {SYS010,2311) F (80) BUFFERS (2) ) ; 

DECLARE CUHCARD FILE INPUT RECORD 

ENVIRONMENT (MEDIUM (SYSIPT , 2540) F (80)) ; 




I READ: READ FILE (CUMCARD) INTO (SEHGRADECARDS) ; 
I WRITE FILE(IJSYSIO) FROM (SEMGRADECARDS) ; 

ItB: 



Figure 75. Creation of Sequential Disk File 
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// JOB CDHDPDT 




// OPTION LINK, SIM, ERRS, 60C,NODECK, LIST, LISTI 




// ASSGN STS01C,X'291' 




// DLBL IJSYS10,' DATA-FILE' 




// EXTENT SIS010,PLID03, 1,0, 1500,250 




// EXEC PL/I 




i>xsic2» vmKmmm<mwm immy^ 




/T\ DECLARE IJSYSIO FILE UPDATE RECORD 

vi/ ENVIRONMENT (MEDIUM (SYS 01 0,2 311) F(80)); 






/^ DECLARE CUMCARD FILE INPUT STREAM 

\3y ENVIRONMENT (MEDIUM (SYSIPT, 2540) F(80)); 






mcmm &im cHSJu^oi^d)! 




i:aBCjM^<3^,Ai^ia>^x<m«s H$9nu 






DECLARE 1 SEMGRADECARDS , 






2 SEMHOURSATTEMPTED PICTURE 


•99V9', 




2 SEMHOURSOFNOCREDIT PICTURE 


'99', 




2 SEMGRADEPOINTS PICTURE 


'99V9', 




2 SEMGRADEPOINTAVE PICTURE 


•9V999' , 




2 TOTHOURSATTEMPTED PICTURE 


•999V9', 




2 TOTHOURSOFNOCREDIT PICTURE 


•99', 




2 TOTGRADEPOINTS PICTURE 


•999V9' , 




2 CUMULATIVEGRADEPOINTAVE PICTURE 


'9V999' , 




2 TOTHOURSTOWARDGRADUATION PICTURE 


•999V9' , 




2 SEMHOURSOFFORGGRADES PICTURE 


•99', 


® 


2 MAJOR PICTURE 


•999', 


2 MARITALSTATUS PICTURE 


•9', 




2 ADVISOR PICTURE 


•999' , 




2 CLASSIFICATION PICTURE 


•9', 




2 COLLEGE PICTURE 


•9', 




2 SEX PICTURE 


•9', 




2 STUDENTIDNUMBER PICTURE 


•99999', 




2 STUDENTALPHANUMBER PICTURE 


•99999', 




2 SEM PICTURE 


•9', 




2 YEAR PICTURE 


•99', 




2 AFFILIATION PICTURE 


•9', 




2 STUDENTNAME CHARACTER (23), 






2 CONTROLCODE CHARACTER ( 1 ) ; 




wcyum wmm asmizi , 


;-v'-i. ■' ■■■■.■■:;;::■■■■■■■■■..■■■■■.:. ■; ■■..■■ '■ ■.■■..::■■.■..'■ ■■ ":■■.■ 


CUftMB Cffilit<2^^ 




/ imxiotE mmier OGMto)! 


■ ''■' .■.■■.■..,, 


BBc^yy^ m wi<:mm *%^^9%* <:mim <m>s^m 




Qwm wjxMium^im fVtmicmOim} $ 




/« T&m cxsm woR dipd&te abs as toLLO^s " M2* CHmrr m>ms ahd | 


/J3\ GRADE POINTS ARE OF FORM R+3.0 +9.0 . (L 
^^ R CARDS ARE REGULAR HOURS, GRADE POINTS 


E'lTER, F9.0,F10.0) 


CHANGES . 


^ F GRADE CARDS MAY BE POSITIVE OR NEGATIVE AND ONLY AFFECT TOTAL | 


>< HOURS ATTEMPTED. NO-CREDIT CARDS ARE OF 


THE CHANGE NO HOURS 1 


Vj$/ 1 ONLY AND ARE OF THE FORM N3 . (LETTER, F9.0) */ | 


(2]) 1 /* A = CHANGE HOURS ATTEMPTED ONLY. */ 




>< 1 /♦ G = CHANGE HOURS TO GRADUATION ONLY. */ 




(2$ /♦ wimm « FiisT TWO lsttsks o^ xjist same oh file. */ 


/♦ aoum « ttWT wo t^s^rms c^ lAs^r nmie ok card, ♦/ 


/♦ 1234$«78^Oi2345«78^0i234S678»Ol23i5678&O123456789G */ 


/♦ I2345AB ItfS. ^i2» r-6. 0. 


*/ 


^^ m Ba«>FILS (la'SYSlO) G0«O S^Pf 




(4) 1 GET EDIT ( ID, CNAME, DUMMY) (COLUMN (1) ,F (5) ,A (2) ,A(3) ) ; | 


Oe^liE « CHftliBi 


1 



Figure 76, Updating Sequential Disk File (1 of 3) 
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00 » IPj 

LOOP: T?EAD FILE (IJSYS10) INTO (SEMG-RADECA?DS) ; 
FMHB « SGBSTB (STUDlllTfiHB^ l^aV; 

IF STUDENTIDNUMBEB = ID THEN GO TO UPDATE; 

ELSE IF STUDENTIDNUMBEH < ID THEN GO TO LOOP; 
ELSE 00; 

?GT BBI7 {' SfuDSSf ID fROo Fltl* ,STU|fll73;Piririli^lV * 

* Cmnti IB SilaBil* «xB } fMlF«lk^7(«K^»l^(^>l » 

GO TO CBBCKHBXTC&BC; 

BHD; 
/* CBBCK PIBSt TfO LltTBBS OB ST9BB»t USt ««1B */ 
SPDATB: IP n*8B -.« CiUHB THBl GO TO ZDBSIOB; 
E^OT BBI? (S70BBif7»li8B} (SIIPt2}«&n 

POT BDrr {• BSFOBB tTPD&TB*) (SXXB,I) $ f 

POT EDIT (» 1B»,ID,« fttl^HiSCB&tfi«* *0T, BBS, %Tt***' 

TOTHOUHSiTTBarrBB, • BBS, BC*, 

TOTHOUBSOPBOCBBBITr • eBB&B tTSf», f07aBiB19aXB7S« 

« BBS. TO GBAD.S TOTBOOBSTOBIBBQBIDBiyiOi 

) { A,y(6) ,A,A(i),AeyCS,1>r*#B($*l3**fr(4),*,f C*Hs 

/'^ SCAS BBST OP CiSB 1«D BPBITl fill SXBCl IB &«» ht^BM fItlBV 

HBZTBATA: GBT EDIT (SIGB) |I{1)>S 

IF SIGN = '!?• THEN GO TO HODHS; 

IF SIGN = 'F' THEN GO TO FGRADE; 

IF SIGN = »N» THEN GO TO NOCBEDIT; 

IF SIGN = «P' THEN GO TO PBOBATIOH; 

IF SIGN = 'A' THEN GO TO ATTHODBS; 

IF SIGN = »G' THEB GO TO GBADHODRS; 

IP SIGB <^:« « * fB^ti>:#0 :fl»;'Miiiii^^i.:^^l^iiiM^^^ 
BOUTS: GET EDIT (CREDITHODBS/gHADEPOINTS) (F (9, 0) ,P { 10 , 0) ) ; 

TOTHODBSATTEHPTED = TOTHOOBSATTEaPTEE + CBEDITHODBS; 

TOTGRADEPOINTS = TOTGBADEPOINTS + GBADEPOINTS; 

TOTHODBSTOHABDGBADOATION = TOTHOOBSTOHABDGBADOATION 
+CREDITHOURS; 

GO TO NEXTDATA; 
FGRADE: GET EDIT (CREDITHODBS) (F(9,0)); 

TOTHODBSATTEHPTED = TOTHODBSATTEHPTED 
+ CREDITHODRS; 

GO TO NEXTDATA; 
NOCREDIT: GBT EDIT (CREDITHODBS) (F(9,0)); 

TOTHODRSOFNOCREDIT = TOTHOUBSOFNOCBBDIT + CBEDITHQORS; 

TOTHOORSATTEMPTED=TOTHODBSATTEMPTED ♦ CREDITHODBS; 

T0THODRST0WARDGBAD0ATIOH=TOTHODBSTOWABDGBAD0ATION+CBEDITH0DBS; 

GO TO NEXTDATA; 
PROBATION: C0HTR0LC0DE=»5» ; 

GET EDIT (DDHMI) {F(9,0)): 

GO TO NEXTDATA; 
ATTHOURS: GET EDIT (CREDITHODRS, GRADEPOINTS) (F (9, 0) ,F ( 10, 0) ) ; 

TOTHODRSATTEMPTED = TOTHODBSATTEHPTED ♦ CREDITHODBS; 

GO TO NEXTDATA; 



Figure 76, Updating Sequential Disk File (2 of 3) 
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GUADHODBS: GET EDIT (CBEDITHOORS^GEfiEEPOINTS) (F {9, 0) ,F ( 10, 0) ) ; 
TOTHODESTOWAEDGRADOATION = TOTHODRSTOTJARDGRADOATION 

+CEEDITHODBS; 
GO TO NEXTDATA; 
COHBECTFILE: 

EEHBITE FILE (IJSYSIO) FBOU (SEMGBADECIBIJSJ ; 



lEEEROB: PUT EDIT (• ID EBROB, UPDATE ID»,ID,» ALPHA' ,CHAHE, • FILE I 
D»,STODENTIDNDHBEB,» FILE ALPHA* ,FNAHE) 

{SKIP,A,F(6),A,A(3) ,A,F(6) rA,A(3)) ; 
GO TO NEWCABD; 
DATAEBBOR: PUT EDIT (» DATA EBBOE, UPDATE ID»,ID,« ALPHA* ,CNAHE) 
(SKIP,A,F(6),A,A(3)) ; 
GO TO NEWCAED; 



MSB m m cmMwctfi^n 



Figure 76, Updating Sequential Disk File (3 of 3) 



// JOB CUMPCH 

// ASSGN SIS01C,X»291» 

// DLBL IJSYSIC 

// EXTENT SIS010,PLID03, 1,0, 1500,250 

// OPTION LINK, SYH, LIST, EBBS, 60C,NODECK,LISTX 

// EXEC PL/I 



© 
® 




DECLABE IJSYS10 FILE INPUT EECOED 
BUFFEEED 

ENVIRONMENT (MEDIUH(SYS010, 2311) F (80) BUFFERS (2) ) ; 
DECLABE CUMCAED FILE OUTPUT EECOED 

BUFFEEED 

ENVIEONHENT(HEDIUH(SYSPCH,25aO) F (80) BUFFERS (2) ) ; 

r»i$iiiiicii^ ciMMIIiph'l 
mm t%t^ mstsm ^wtiMt^cmmikmt 

BEAD: BEAD FILE (IJSYS 10) INTO (SEHGRADECABDS) ; 
iEITE FILE (CUMCAED) FROM (SEHGBADECAEDS) ; 



Figure 77. Punching Disk Data Into Cards 
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xh@ jj\j W11IXj£ Stcit6ni6nt 

The program shown in Figure 78 shows how 
the sum of the series 1 + 1/2 ■?■ 1/3 + 1/4 + 
1/5 + ... may be computed using the DO 
WHILE statement. 

WHILE: PROCEDURE OPTIOMS (MAIN) ; 
SUM=1; 
N=l: 

DO WHILE vl/N > l.E-3*SuM): 
N=N+1; 

SUM=SUM+1/N; 
END; 

PUT LIST (SUM, N); 
END; 

Figure 78. Example Illustrating The Use of 
The DO WHILE Statement 



Using The Console For Communications 

The example in Figure 79 (encircled numbers 



how the console may be used for comniunica- 
tion with a program. 



Four files are used: a tape input file 
(D , a tape output file (2) , a card output 
file Q) , and a print file (no declaration, 
default). The input from the tape xnput 
file may be written on tape, punched into 
cards, or printed. The answer as to what 
is to be doney must be aiven by the opera- 
tor using the console (4) . The operator 
has to type any combination of "PRINT", 
"COPY", or "PUNCH". 



The answer is then scanned by the pro- 
gram to determine first whether COPY 5 , 
then whether PRINT © , and finally whether 
PUNCH (Z) has been returned. If the reply 
that is searched for is not found in 
ANSWER, is returned by the INDEX built-in 
function. 

Depending on the answer of the operator, 
the input is written onto tare (§) , punched 

^ ^ , ^^ ^ ^^ . 
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// JOB M0N_U3 

* PAUSE READY TAPES MASTER ON 180 

// ASSGN SYSC1C,X' 182' 

// ASSGN SYSOl 1,X' 18T 

// OPTION LINK, LIST, SYM, ERRS, 60C,NODECK,LISTX, DUMP 

ACTION NOMAP 
// EXEC PL/I 



Q) 

® 
® 



® 
® 
® 
® 



® 

® 
® 



OTIL: PIOCEDUBE OPflOHS (UAIS) ; 

DECLARE TAPEIN FILE RECORD SEQOENTIiL INPOT EHVIHGNHENT 

(MEDIUM (SYS010,2400) CONSECUTIVE F(800,80) BUFFERS (2) 
NOLABEL) ; 
DECLARE TAPEOU FILE RECORD SEQUENTIAL OUTPUT ENVIRONMENT 

(MEDIUM (SYS011,2U00) CONSECUTIVE F(800,80) BUFFEBS (2) 
NOLABEL) ; 
DECLARE CARDOH FILE HECOBD SEQUENTIAL OUTPUT ENVIRONMENT 

(MEDIUM (SYSPCH,25U0) CONSECUTIVE F (80) BUFFERS (2)); 
CECLItltE CilD CB&5 (80) ; 
DECLJIBB iiiSaSK CB&H (20) ; 

DSCL&HS (COPIBIT,F«lHTBlT,MliCaBlt) CS18(I| ; 
DECiiBS LOGIC CHiE {3} ; ) 
OH SHDFILE (lAPSIli} QQ TO BOIIB; 
STJIUT: 

iHSWEB « » ♦; COPIBlt » > »; 
DISPLAY 



('TYPE CONTROL WORDS - PRINT, PUNCH, COPY- ANY COMBINATION 

* } HBFLi (iirsvit); 



■K, 



I M=INDE2 (ANSWER, 'COPY') ; 

IP 8 «»« tHEll COJIBIf* •I'J 
I H=INDEI (ANSKSR, 'PRINT') ; 

IF I! **« THES ?«l»tBXf » 'I'} 
I M=INDEX (ANSWER, 'PUNCH') ; 

IP B -»« T8II FUBCSBIX « *1*; 

ELSE DO; 

LOQIC « COFlBXf M BlIBfBrr It 

IF LOGIC •'» ' ' 'mm 0^ 

DISPLAY <'IiiViU;.II> I^SFC^E, 'TR3f fsJS»m*}$ 
(^ TO START? 

EbiD; 

OPES FILE CTAPSIH) 

IF COPYBIT » '1' THE» 
OPEH FILE (TAPEOO) ? 
IF PU13CHBIT « '1' THWi 
OPEK FILE (aMUXKJ)f 
LOOP; BEM> FILE (TAPEIH) Xm?0 tCAID) s 
I IF COPYBIT = '1' THEN 

I WRITE FILE (TAPEOU) FROM (CARD) ; 
I IF PUNCHBIT = '1' THEN 
I WRITE FILE (CARDOU) FROM (CARD) ; 
I IF PRINTBIT = '1' THEN 
I PUT EDIT (CARD) (SKIP,A(80) ) ; 

GO TO I^DOP* 
DONE: CLOSE FILE (TAPEIli) | 
IF COPYBIT » '1' TSm 

CLOSE FILE (TAPEOP) ? 
IF PUIiCBBIT » '1' THiail 
CLOSE FILE (CA»DOa) j 



Figure 79, Using the Console for Communications 
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(Where more than one page reference is given, major reference appears first.) 



ABNORMAL attribute 141 

Access nnethods 35 

ACTION statetnent ..................... 19 26 

ALIGNED „ 137 

Alignment requirements of data 67 

All option , 14 

Appendage. 74 

Arguments, passing of 46 

Arithmetic constants ,. 137 

Arithmetic data (storage 

requi rements ) ,,,,,,,,,e,,,,,,,, = ^, 60 

Array bounds... ,,,,,,,,,,,,,, 65 

Arrays , 137 

Arrays of structures.... 51,137 

Assembler modules 46 

Assembler modules calling PL/I 46 

Assembler modules, linking of 44 

ASSGN statement 13 

cTLu L.rxi_>Uue j.acL.onzauxon • ............... xo / 

Attributes, redefining. .,,.... 52 

Autolink feature... 20 

AUTOMATIC data storrage 63, 138 

AUTOiyiATIC variables... 46 

Background partition 11,18 

Background processing 11, 18 

BACKWARDS attribute 39 

BACK^JARDS files 39 

BASED attribute. . « = = . . * . 52 

BASED data storage 63 

Based structures 52 

Based variables 52 

Based variables with structures 52 

Binary 

fixed data 60,138 

fixed and float variables 67 

fixed data., 60,137 

float data 60,137 

Bit strings 137,62 

Blanks 137 

Block (of data) 27 

Blocks (of program) 137 

Block length 137 

Block prologue 81 

u J.OCK Sxze. •.......•••••.......••.....•. jx 

Block table listing 92 

Blocked records , 31 

Blocking 51 

Blocksize option 137 

Boundary requirements 65 

Bounds of an array 64 

Buffer (length) 35 

BUFFERED attribute 35 

Buffers ,..,., 72 

Buffering 35 

Buffering attributes 35 

Built-in functions. . , , 96, 138 



CALL statement 44,46 

Calling Assembler modules. 46 

K,n.±n.u <^^ L.XUJ.X V <uc ± JL\~H-t o cci L-ciiidiL./ .«.••«... ±J 

Cataloging 24 

foreground programs. 26 

into core- image library... 24 

into relocatable library 24 

label information 41 

relocatable modules 24 

CATALR statement 24 

Chain— back word** »«*«*,«»....«,,.....,, . 58 
Chaining of DSAVs= *=»==.»».»***.»..**-- » 58 

Character strings......... 138,62 

CHARACTER variables 67 

Checkpointing 47 

CNTRL macro , 47 

COBOL subroutines (calling of),. 44 

Coded arithmetic data (storage 
requi reraents ).......................... 60 

Coded arithmetic variables (default 

attributes of) , 136 

Comments statement 16 

Compatibility 138,70 

Compilation requirements 18,5 

in background partition. 18 

in foreground partition 18 

Compilation under DOS/TOS 17,20 

Compile and catalog....... 25 

Compile-time diagnostics 107 

Compile-time options 16,15 

Configuration (supported maxiinuiri) 6 

CONSECUTIVE files 27 

Console (using console for 

communication) 64 

Constants, representation of 64 

Control field 34 

Control routine, PL/I 82 

CONVERSION condition 140,40 

Conversion , 50,138 

example .^. 143 

possible combinations of 95 

requirements. 70 

subroutines , 70, 93 

Core-image library 11 

Correspondence defining 52 

Cross-i.ef erence listing................. 91 

CSECT names 21 

Cylinder 33 

Cylinder index 30 

DA (DLBL statement) 37 

DASD file label formats 102 

Data 

alignment 67 

aggregates ,,, 137 

area 37 

descriptor 60 

files 27 

items 60 
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storage 138 

storage mapping. 65 

storage requirements 60 

conversion, possible combinations 95 

Date (in job control) 37,38 

Decimal 

data, precision of 53 

fixed and float variables 67 

fixed data 138,61 

float data 138,61 

DECK option (OPTION statement). 15 

DECLARE Statement 138 

DEFINED attribute 52, 138 

DELETC statement 24 

Deleting from libraries 24 

DELETR statement 25 

Device address 13 

Device specification for tapes 13 

Diagnostic messages 

compile-time. 107 

object-time. 130 

Dimension attribute 138 

Direct access method 29,35 

Disk and Tape Operating Systems 10 

Disk files.... 36 

creating and updating sequential 150 

Disk file processing 36 

Disk labels 36 

Disk organization 33 

DISPLAY statement 139 ,53 

Displaying intermediate results 

(DyNDQMP) 58 

DLAB statement 37 

DLBL statement 37 

DO loops 

optimization of.. 54 

DO statement ., 139, 154 

DOWN optic?n 14 

DSA- .- 80 

chaining •••- 58 

layout 46 

DTF program 72 

DTP table 72,47,58 

DTFCD. , 72 

DTFDA. 74 

DTFDI 76 

DTFIS 75 

DTFMT 73 

DTFPR 73 

DTFSD 74 

Dump interpretation 58 

DUMP option (OPTION statement) 15 

Dynamic storage area (DSA)... 80,46,58 

DYNDUMP routine 58,139 

E- format outputs 54 

Edit-directed data transmission 54 

END statement (PL/I) 139 

ENDFILE condition 140, 40 

End-of-data-f ile statement 16 

End-of - job statement , 16 

EMDPAGE with multiple-line PUT 55 

Entry name parameter 141 

Entry points 21 

ENTRY statement 21 

Error messages 

coraoile-tirae 107 



object-time 130 

Error statistics (for mathematical 

functions) 70 

Errors 

due to multiple secondary entry 

points 21 

due to multiple CSECT names.... 21 

tracing object-time 31,56,58 

tracing compile-time 90 

ERRS option (OPTION Statement) 15 

EXEC statement 13 

Execution requirements 6 

Execution-time errors , » 58 

EXHIBIT CHANGED 56 

Expiration date 36 

Exponent subfield. 139 

Extent 33 

EXTENT statement 33,37 

External 

attribute... . , , .. .. 50,85 

data storage 63 

procedure. 21 

structures 140 

symbol table listing 91 

F-format output .,-, 54 

Factorization of attributes .,137 

File..... 27 

appendage 47 

arguments ,-«.,,.., 47 

attributes 135, 35 

declaration checklist.. 135 

declarations 72 

generation number... 39 

identification, 37 

label formats ■ 102 

labels ^.. 36 

module ^, ,..-,,..... 24 

organization - 27 

parameters 46 

sequence number , 38 

serial number 38 

unbuffered. 35, 139 

version number - 39 

Fixed blocked records..., 34 

Fixed unblocked records 34 

Floating-point registers 44 

Foreground partition 11,18 

Foreground program 11, 26 

Foreground save area.- 18 

Format constants 139 

FORMAT statement 139 

FORTRAN subroutines (calling of) 44 

Function reference 46 

Generated catalog control statements.... 25 

Generation number. 39 

GET statement 139 

Hardvjare interrupts... 130 

Header label , 36 

Housekeeping errors,.... 131 

Identification (file) 38 

Identifiers 139 

IF nesting 139 
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IJKEXHC 56, 139 

IJK3ZCI ,- 48 

IJKSZCN 46 

IJKTROF 56,139 

XkJKTRON. .•-.•..••.•••.•.••••••••••«•• oo, 139 

IJKZL macro instruction. 5U 

IJKZWSI U8 

Implicit declaration.. i 139 

Implied subroutine calls. -. 96,70 

Including 

by cortipi lation ,... 20 

f roro the relocatable library. ......... 20 

object card decks 20 

object modules 20 

Independent overflow area 31 

Index area 30,38 

INDEX built-in function 154 

Indexed files 29 

options for, ,,,,,,,,,,,,,ee = ,^, 33 

Indexed- sequential 

file^ creation of 29 

organization , 31 

INITIAL attribute 139 

Initial Program Loader 10 

I/O device assignment 12 

listing of....... 12 

X/0 errors ............................. xj^ 

I/O processing^ 35 

I/O statement 

format checklist 134 

nesting of 140 

I/O storage requirements ,... 72 

I/O subroutines (list of) 100 

IOCS logic module,.,, 76 

IPL , . . . , 10 

IRREDQCIBLE attribute 141 

ISC (DLBL statemenf* 37 

ISE (DLBL stateitient,' .................... 37 

Iteration specification (DO nest)...... 139 

Job 12 

Job Control program 12 

Job Control statements 12 

JOB statement 14 

Job step 12 

Key 27,29 

KEY condition 31,140 

KEY option 29,33 

KEYFROM option 29,33 

KEYLENGTH option 29,33 

KEYTO option 33 

Label. 36, 140 

constants (storage) 63 

control statements..... 36 

data 63 

(END Statement) 139 

information, cataloging of 41 

processing 36 

-program communication ,. 41 

statement examples 39,40 

variables, ,,* ...,,, 53,67 

Labeled files, link-editing.... 40 

Labeled tape files 36,40 

LBLPYP statement 40 

Leaf (of overlay tree) 85 



LEAVE option 39 

Level number (structures), 142 

Librarian » ,..- 11 

control statements 24 

Library maintenance (TOS) .............. . 26 

maint enance runs 25 

standard save area (LSSA) 58 

subroutines , 8 

LINK option (OPTION statement) 15 

Linkage Editor 18,10 

control statements. ,..«..,.....,...,. . 18 

pa.oga.aui xo 

storage map 58,18 

Link-editing 

foreground programs....... 18 

labeled files 40 

multiphase foreground programs. ...... . 88 

overlays ., - 87 

Linking Assembler modules......--,,.- 44,46 

Linkincf conventions* -***«»..-*.-«. ..««.» 44 
LIOCS t able = = = . = = = ,» = = .»,».»»*,»»,****». 41 

LIST option (OPTION Statement) 15 

List-directed data transmission.., 54 

List I/O .. 140 

Listing of I/O assignments,,, 14 

Listings, program...,- 90 

LISTIO statement - , , 14 

LISxO Option (PROCESS statement),,.,.,,. 17 

LISTX option (OPTION Statement) 15 

Locating execution-time errors ,,,,. 58 

LODIS macro 39 

LOG option (OPTION statement) 15 

Logical depth (structures) , 66 

Logical device address 12 

Logical units » 13 

Machine features - 6 

Machine requirements.-... - 6 

Magnetic tape, positioning of..,,,.,,,,, 40 

MAIN option 140,46 

MAIN procedure .-. .,^,,, 46 

Mapping (storage) 65 

Master index , ,. , 3n 

MINSYS option (OPTION statement) , 15 

Module names ,,. 24 

MTC statement 14,39,40 

Multi-extent file., 37 

Multi-file volume ..,, 39 

Multiprogramming -..,,..,,,- -,, 11 

Multi-reel file 27 

Multi-volume file - - 39 

Names ,, 140 

Nested blocks. , . 137 

Nested ±/o statements-.,,, «. 140 

NEWVOL library statement 26 

NOAUTO option (PHASE or ACriON Stmt),,., 20 

NODECK option (OPTION statement) 15 

NODUMP option (OPTION statement) 15 

NOERRS option (OPTION statement) 15 

NOLINK option (OPTION statement) 15 

NOLIST option (OPTION statement) 15 

NOLISTO option (PROCESS statement) 17 

NOLISTX option (OPTION statement) 15 

NOLOG option (OPTION statement) 15 

NOOPT option (PROCESS statement) 17 

NORMAL attribute 141 

Normalized data 51 
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NOSTMT option (PROCESS Statement) 17 

NOSYM option (OPTION statement) 15 

NOXREF option (OPTION statement) 15 

NULL 139 

Numeric data (storage).. 62 

Numeric fields in edit-directed I/O.. 51,5t| 

Object code listing-.... 92 

Object module 8 

Object- time diagnostics. 130 

Ob ject^tirae errors ( locating) .,..* 58 

Object-time storage layout 10 

Offset table listing 91,58 

ON-conditions 134,140 

ON-condition comments. .• 130 

ON statement 140 

ONSYSLOG option , , 141 

OPEN statement 36 

OPT option (PROCESS statement) 17 

Optimization (of compiled code) 17 

OPTION statement 15 

OPTIONS attribute , 141 

Options 

supported by job control 17 

not supported by job control ,. 17 

Overflow area 30 

independent 37 

Overhead ,,,., 79,8 

Overlap, seek time. 47 

Overlapping I/O operations 35 

Overlay ^ 85,51,139 

defining 52 

example. 87 

rules for using ,... 85 
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PAGESIZE option 141 
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PAUSE statement. 16 

Phase , 85,8 

loading. 86 

names. 24, 85 

PHASE statement 19,87 

Physical device address 12 

PICTURE attribute 141 

data , 141 

specifications 55 

Picture-specified 

character strings 62 

data (storage)..,. 62 

PICTURE variables 67 

Pictures, use with stream-oriented 

data transmission. 55 

PL/I control routine.. 82 

Pointer variables... 63,67 

storage 63 

Positioning of magnetic tapes 40 

Precision (of arithmetic constants)...., 64 

Precision (of decimal data) 53 

Preformatting REGIONAL files 28,149 

Prime data area 28 

Private relocatable library 20,23 
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contained in relocatable library 89 

default condition 141 



module 8, 24 

PROCEDURE statement 141 

PROCESS statement 16 

PROG option.-.., -. 14 
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Pseudo variables 70,96 

PUT statement 141 

Qualified names , 141 
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Record „ . . 27 
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RECORD condition . * 33 
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REDUCIBLE attribute 141 

REGIONAL files 27 
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REGIONAL (1) file... 147 

Register usage for linking...... 44 

Relative track number 38 

Relocatable library............... 89,11,24 

private 20 

Remote format item......... 139 

Remote FORMAT statement 139 

Repetition factor 141 

Repetitive specification 139 

Replication factor 139 

REPLY option 139,53 

RESET statement, 16 

Restarting 47 

Restrictions on PL/I language 137 

Retention period, 37,38 

RETURN macro , 4 5 

Returning registers..................... 45 

Rewind operation 40 

Root 8 5 

Rounding on output^..., 55 

RSTRT Statement 47 

Save area 46 

SAVE macro 45 

Saving registers...., 44 

Scale factor „ 142 

SD (DLBL statement) 37 

Secondary entry points , 89 

Seek time overlap.,.,..., •••' ^'^ 

Segmentation of programs , 50 

Self-relocating programs. 20 

Sequence number (file) 39 

Sequential access method..., 27,35 

Serial number (file)., , 38 

SIZE overflow , 53 

SKIP 139 

Source 
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program listing...., • , 90 

statement library 11 

text and object program 83 

Split-cylinder technique 34 

Split cylinder track,,., 38 

Standard I/O assignments 12 
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Statement format 50,142 
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STATIC data storage ,,,. 63 
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STMT option (PROCESS statement) 17 
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for data 60 

for dynamic storage.' 80 

examples for computing »,. 83,87 

for I/O '. 72 

for PL/I control routine 82 

for program expansion. 50 

for static storage- .......... 79 

for subroutines 70 

STREAM files (blocksize options) 137 

String data, storage of 62 

STRING pseudo-variable, .,. 143 

Stringency level 66, 67 

Structure 51 

declaration 142 

externals ............................ 140 

level numbers 142 

mapping 66, 51 

mapping rules , 67 

m.axirpum depth 142 
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STXIT macro 48 
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Subroutine storage requirements 70 
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statements) 71 

conversion ,,,. 93 

SUESTR built-in function 144 

Supervisor 10 

Symbol table listing 90 

Symbolic unit 37 

SYM option (OPTION statement) 15 

SYS option 14 

SYSCLB 12,13 

3YSIN. . . p 13 ,36 ,78 

SYSIPT 12, 13 

SYSLNK 12,13 

assignments for , 19 

SYSLOG 12,13 

SYSLST 12,13 

SYSOUT 12 

SYSPGH 12,13 
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SYSRLB 20 

SYSOOl-003 12,13 

System control programs -.. 11 
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UNBUFFERED attribute 35 
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UNSPEC 51 
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User Program Switch Indicator 16 
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VariaiDle unblocked records.... 35 
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